HTTP Redirect Codes for RESTful Services
draft-hunt-http-rest-redirect-00

Abstract

This specification clarifies the use of HTTP redirect codes when used with RESTful services.

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

This Internet-Draft will expire on July 19, 2014.

Copyright Notice

Copyright (c) 2014 IETF Trust and the persons identified as the document authors. All rights reserved.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.

Table of Contents

• 1. Introduction
• 1.1. Requirements Language
• 2. RESTful Redirection
• 2.1. Temporary Redirection
• 2.2. Permanent Redirection
• 2.3. Alias Redirection
• 2.3.1. Self Referencing Alias
• 3. Acknowledgements
• 4. IANA Considerations
• 5. Security Considerations
• 6. References
• 6.1. Normative References
• 6.2. Informative References
• Author's Address

1. Introduction

Representational State Transfer or REST is an architectural style for networked systems as described in Dr. Roy Fieldings Ph.D. dissertation [Fielding-REST]. Though [Fielding-REST] is not dependant upon any particular protocol, this specfiction pertains to services built upon HTTP as defined by [RFC2616] 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 [RFC2616]) and HTTP Redirect code 308 (as defined in [I-D.reschke-http-status-308]) with RESTful services.

1.1. Requirements Language

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 [RFC2119].

2. RESTful Redirection

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.

2.1. Temporary Redirection

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.

2.2. Permanent Redirection

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.

2.3. Alias Redirection

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.

2.3.1. Self Referencing Alias

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.

3. Acknowledgements

This specification was developed based on discussions within the SCIM working group. The author would like to thank the members for their input.

4. IANA Considerations

This memo includes no request to IANA.

5. Security Considerations

All security considerations that applye to HTTP redirects as specified by [RFC2616], apply to redirect 308.

6. References

6.1. Normative References

6.2. Informative References

Author's Address