HTTP Redirect Codes for RESTful Services

Representational State Transfer or REST is an architectural style for networked systems as described in Dr. Roy Fieldings Ph.D. dissertation . Though is not dependant upon any particular protocol, this specfiction pertains to services built upon HTTP as defined by hereafter called RESTful services. Section 10.3 of the HTTP specification defines several redirect response codes normally used to redirect user-agents (browsers) in response to HTTP requests. This specification clarifies the use of HTTP redirect code 307 (defined in ) and HTTP Redirect code 308 (as defined in ) with RESTful services.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

In order to preserve the integrity of REST operations, HTTP redirection codes 301-306 SHOULD NOT be used unless the service provider is aware the client is in fact a user-agent. Redirection code 301-306 require clients to convert requests to HTTP GET or HEAD and are not normally suitable. REST servers MAY issue two types of HTTP redirects: HTTP redirect 307 for temporary redirection and HTTP redirect 308 for permanent redirection. Upon receiving redirect code 307 OR 308, REST clients SHOULD preserve the HTTP request and the implied REST operation by applying the same request to the new resource location specified in the redirect.

A service provider MAY temporarily redirect clients using HTTP 307 as specified in RFC2616. The original HTTP action MUST be preserved. The REST client MUST use the original permanent URI when referencing the affected REST resource in any other REST operations or REST resource. If there is no user-agent involved in the transaction, the REST client MAY proceed by automatically processing the redirect. Clients MUST ensure that the new location keeps the operation intent intact.

In the event that a REST resource has been relocated or reassigned, a service provider MAY issue an HTTP 308 redirect. This redirect informs the REST client of the new permanent URI for the object. REST clients MUST ensure that the new address keeps the operation intent intact and the same HTTP verb is used. The REST client MUST use the new permanent URI when referencing the affected REST resource in any other REST operations or REST resource. If there is no user-agent involved in the transaction, the REST client MAY proceed by automatically processing the redirect.

REST based services MAY use HTTP redirection code 308 in order to permit aliasing of RESTful resources. Servers that DO NOT support REST resource aliases SHOULD respond with HTTP 404 (not found) if an alias request is received or is not otherwise resolvable.

In situations where the client wishes to refer to the current security context of the user, the server MAY translate a URI of the form "<server-prefix>/me" to mean the resource represented by current authenticated subject where "<server-prefix" is the URI fragment of the REST service root. If "<server-prefix>/me" does not resolve to a resource within the service endpoint requested, the service provider MUST respond with HTTP 404 (not found). If subject is resolved to a resource, the service provider MAY use HTTP 308 to redirect the SCIM client to the permanent URI of the authenticated subject.