Internet DRAFT - draft-hunt-http-rest-redirect
draft-hunt-http-rest-redirect
HTTPbis P. Hunt, Ed.
Internet-Draft Oracle Corporation
Intended status: Informational January 16, 2014
Expires: July 20, 2014
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 20, 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.
Hunt Expires July 20, 2014 [Page 1]
Internet-Draft draft-hunt-http-rest-redirect-00 January 2014
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Requirements Language . . . . . . . . . . . . . . . . . . 2
2. RESTful Redirection . . . . . . . . . . . . . . . . . . . . . 2
2.1. Temporary Redirection . . . . . . . . . . . . . . . . . . 3
2.2. Permanent Redirection . . . . . . . . . . . . . . . . . . 3
2.3. Alias Redirection . . . . . . . . . . . . . . . . . . . . 3
2.3.1. Self Referencing Alias . . . . . . . . . . . . . . . 4
3. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 4
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 4
5. Security Considerations . . . . . . . . . . . . . . . . . . . 4
6. References . . . . . . . . . . . . . . . . . . . . . . . . . 4
6.1. Normative References . . . . . . . . . . . . . . . . . . 4
6.2. Informative References . . . . . . . . . . . . . . . . . 4
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 5
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.
Hunt Expires July 20, 2014 [Page 2]
Internet-Draft draft-hunt-http-rest-redirect-00 January 2014
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.
Hunt Expires July 20, 2014 [Page 3]
Internet-Draft draft-hunt-http-rest-redirect-00 January 2014
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
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
6.2. Informative References
[Fielding-REST]
Fielding, R., Ed., ""Architectural Styles and the Design
of Network-based Software Architectures", Doctoral
Dissertation, 2000.", .
Hunt Expires July 20, 2014 [Page 4]
Internet-Draft draft-hunt-http-rest-redirect-00 January 2014
[I-D.reschke-http-status-308]
Reschke, J., "The Hypertext Transfer Protocol (HTTP)
Status Code 308 (Permanent Redirect)", draft-reschke-http-
status-308-07 (work in progress), March 2012.
Author's Address
Phil Hunt (editor)
Oracle Corporation
Email: phil.hunt@yahoo.com
Hunt Expires July 20, 2014 [Page 5]
