Internet Engineering Task Force P. Bryan, Ed.
Internet-Draft ForgeRock
Intended status: Informational February 4, 2012
Expires: August 7, 2012
A Convention for HTTP Access to JSON Resources
draft-pbryan-http-json-resource-01
Abstract
This document codifies a convention for accessing JSON
representations of resources via HTTP.
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 August 7, 2012.
Copyright Notice
Copyright (c) 2012 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.
Bryan Expires August 7, 2012 [Page 1]
Internet-Draft HTTP JSON Resource February 2012
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Resources . . . . . . . . . . . . . . . . . . . . . . . . . . 3
4. Version Control . . . . . . . . . . . . . . . . . . . . . . . 3
5. Operations . . . . . . . . . . . . . . . . . . . . . . . . . . 4
5.1. Create . . . . . . . . . . . . . . . . . . . . . . . . . . 4
5.2. Read . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
5.3. Update . . . . . . . . . . . . . . . . . . . . . . . . . . 6
5.4. Delete . . . . . . . . . . . . . . . . . . . . . . . . . . 7
5.5. Patch . . . . . . . . . . . . . . . . . . . . . . . . . . 7
5.6. Query . . . . . . . . . . . . . . . . . . . . . . . . . . 8
5.7. Action . . . . . . . . . . . . . . . . . . . . . . . . . . 9
6. Request Context . . . . . . . . . . . . . . . . . . . . . . . 10
7. Access Control . . . . . . . . . . . . . . . . . . . . . . . . 10
8. Resource Validation . . . . . . . . . . . . . . . . . . . . . 10
9. Resource Metadata . . . . . . . . . . . . . . . . . . . . . . 10
9.1. Header . . . . . . . . . . . . . . . . . . . . . . . . . . 11
9.2. Object Members . . . . . . . . . . . . . . . . . . . . . . 11
10. Error Response . . . . . . . . . . . . . . . . . . . . . . . . 11
10.1. Members . . . . . . . . . . . . . . . . . . . . . . . . . 11
11. Modifying a Resource Identifier . . . . . . . . . . . . . . . 11
12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12
13. Security Considerations . . . . . . . . . . . . . . . . . . . 12
14. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 12
15. Normative References . . . . . . . . . . . . . . . . . . . . . 12
Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 13
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 13
Bryan Expires August 7, 2012 [Page 2]
Internet-Draft HTTP JSON Resource February 2012
1. Introduction
JavaScript Object Notation (JSON) [RFC4627] is a common format for
the exchange and storage of structured data. Hypertext Transfer
Protocol (HTTP) [RFC2616] is a common protocol for providing remote
access to resources.
This document codifies a convention for accessing JSON
representations of resources via HTTP. This promotes a common remote
access interface across multiple disparate resources and reuse of
conforming server and client software components.
2. Conventions
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].
This document expresses the structure of Request-URIs in examples
using [URI-Template] syntax.
3. Resources
A resource accessed through this convention is represented as a JSON
value with an "application/json" (or derivative) Internet media type.
An accessible resource is a member of a collection of resources. A
collection of resources MUST have a unique location, which is
expressed as a part of the Request-URI of HTTP requests. The server
implementation determines the location of a resource collection.
Each resource MUST have a unique identifier within a collection. The
server implementation MAY establish restrictions on identifiers that
can be used, and reject requests that have identifiers that do not
conform with a 403 Forbidden status code.
4. Version Control
A server MAY implement version control for resources, and use it as
the basis of an optimistic concurrency control mechanism. If version
control is implemented for a given resource, the server MUST expose
the resource version in responses, and clients MUST use preconditions
when performing operations that modify such resources.
If a server implements version control for a resource, and the
Bryan Expires August 7, 2012 [Page 3]
Internet-Draft HTTP JSON Resource February 2012
resource version is incorrectly specified by a client for an
operation that modifies the resource, the server SHOULD indicate this
with a 412 Precondition Failed status code.
If a server implements version control for a resource and the
resource version is not specified by a client for an operation that
modifies the resource, the server SHOULD indicate this with a 428
Precondition Required status code, per [New-Status].
The server implementation determines how a resource version is
computed; it MUST ensure that different values for a given resource
compute different versions. Clients SHOULD treat a resource version
provided by a server as opaque.
The server expresses resource version via the "ETag" response header
and the "_rev" metadata member in JSON object entity responses. The
client expresses resource version via the "If-Match" and "If-None-
Match" precondition request headers.
5. Operations
This convention provides a uniform set of operations, all of which
are implemented via standard HTTP methods. The operations are:
create, read, update, delete, patch, query, and action. The server
implementation MAY conditionally implement any operation.
5.1. Create
The "create" operation allows a client to create a new resource in a
collection. A resource is created in one of two ways: if the client
is requesting a specific identifier, then the resource is created via
the HTTP PUT method; if the server is to select its own identifier,
then the resource is created via the POST method. The PUT method
SHOULD be preferred over POST.
5.1.1. PUT Request
In the PUT method, the identifier of the resource to create is
specified in the Request-URI of the HTTP request. The server MAY
override the requested identifier of the resource and select a
suitable identifier of its own.
To unambiguously request resource creation, the "If-None-Match"
header MUST contain the value "*". If no precondition header
unambiguously requests resource creation or update, the server MAY
use its own means of determining how to interpret the PUT method.
Bryan Expires August 7, 2012 [Page 4]
Internet-Draft HTTP JSON Resource February 2012
PUT /{collection}/{id} HTTP/1.1
Content-Type: application/json
If-None-Match: *
...
[JSON representation of resource to create]
5.1.2. POST Request
In the POST method, the identifier of the resource is not specified.
The Request-URI of the request MUST NOT contain a query component, in
order to distinguish it from the "action" operation. The server MUST
select a suitable identifier for the created resource.
POST /{collection} HTTP/1.1
Content-Type: application/json
...
[Resource representation]
5.1.3. Response
HTTP/1.1 201 Created
Content-Type: application/json
Location: [location of resource]
ETag: "[resource version]"
...
[Resource metadata object]
The "Location" header field contains a URI that identifies the newly
created resource. The optional "ETag" header field contains the
version of the newly created resource. The resource metadata object
also contains the identifier and optional version of the newly
created resource.
If version control is implemented for a given resource, the server
MUST expose the new resource version in the ETag header of the
response.
5.2. Read
The "read" operation allows a client to read a representation of a
resource from the server. It is implemented using the HTTP GET
method. The client MUST NOT include a query component in the
Request-URI, in order to distinguish it from the "query" operation.
If the resulting representation of the resource is a JSON object, it
Bryan Expires August 7, 2012 [Page 5]
Internet-Draft HTTP JSON Resource February 2012
SHOULD contain the JSON "_id" member, and also the "_rev" member if
resource version is supported by the server implementation.
5.2.1. Request
GET /{collection}/{id} HTTP/1.1
...
5.2.2. Response
HTTP/1.1 200 OK
Content-Type: application/json
ETag: "[resource version]"
...
[Resource representation]
If version control is implemented for a given resource, the server
MUST expose the resource version in the ETag header of the response.
5.3. Update
The "update" operation allows a client to update the representation
of a resource on the server. It is performed using the HTTP PUT
method. To cause the PUT method to unambiguously request a resource
update, the "If-Match" header MUST contain the current version of the
resource. If no precondition header unambiguously requests resource
creation or update, the server MAY use its own means of determining
how to interpret the PUT method.
5.3.1. Request
PUT /{collection}/{id} HTTP/1.1
Content-Type: application/json
If-Match: "[resource version]"
...
[Resource representation]
Bryan Expires August 7, 2012 [Page 6]
Internet-Draft HTTP JSON Resource February 2012
5.3.2. Response
HTTP/1.1 200 OK
Content-Type: application/json
ETag: "[resource version]"
...
[Resource metadata object]
If version control is implemented for a given resource, the server
MUST expose the updated resource version in the ETag header of the
response.
5.4. Delete
The "delete" operation allows a client to delete a resource, or
optionally an entire collection of resources. It is performed using
the HTTP DELETE method.
To delete a single resource, both the collection location and
resource identifier MUST be specified in the Request-URI of the HTTP
request. To delete an entire collection, only the collection
location MUST be specified.
5.4.1. Request
DELETE /{collection}/{id} HTTP/1.1
If-Match: "[resource version]"
...
5.4.2. Response
HTTP/1.1 204 No Content
...
5.5. Patch
The "patch" operation allows a client to apply a set of partial
modifications to a resource on the server. This is particularly
useful if the client is provided with redacted representations of
resources and/or does not have permission to modify resources in
their entirety.
The "patch" operation is performed using the HTTP PATCH method, per
[RFC5789]. The supported patch document format(s) to apply the
partial modifications is determined by the server implementation.
Bryan Expires August 7, 2012 [Page 7]
Internet-Draft HTTP JSON Resource February 2012
5.5.1. Request
PATCH /{collection}/{id} HTTP/1.1
Content-Type: application/json-patch
If-Match: "[resource version]"
...
[JSON Patch document]
5.5.2. Response
HTTP/1.1 200 OK
Content-Type: application/json
ETag: "[resource version]"
...
[Resource metadata object]
If version control is implemented for a given resource, the server
MUST expose the updated resource version in the ETag header of the
response.
5.6. Query
The "query" operation performs a parametric query of a resource or
collection, and responds with a result. The execution of a query
MUST NOT incur side effects. It is implemented using the HTTP GET
method. The client MUST include a query component in the Request-URI
to distinguish it from the "read" operation.
To query a single resource, both the collection location and resource
identifier MUST be specified in the Request-URI of the HTTP request.
To query an entire collection, only the collection location MUST be
specified.
5.6.1. Request
GET /{collection}/{id}?{query} HTTP/1.1
...
Bryan Expires August 7, 2012 [Page 8]
Internet-Draft HTTP JSON Resource February 2012
5.6.2. Response
HTTP/1.1 200 OK
Content-Type: application/json
...
[JSON query result value]
The structure of the query result value is determined by the server
implementation.
5.7. Action
The "action" operation performs a parametric action on a resource or
collection, and responds with an optional result. The execution of
an action MAY incur side effects.
The operation is implemented via the HTTP POST request. The Request-
URI MUST NOT contain a query component, in order to distinguish it
from a "create" operation. The request MAY include an entity body.
To perform an action on a single resource, both the collection
location and resource identifier MUST be specified in the Request-
URI. To perform an action on an entire collection, only the
collection location MUST be specified.
If the response contains a result value, then the server SHOULD
respond with a 200 OK status code; otherwise it SHOULD respond with a
204 No Content status code.
5.7.1. Request
POST /{component}/{id}?{query} HTTP/1.1
Content-Type: application/json
...
[Optional JSON value]
5.7.2. Response
HTTP/1.1 200 OK
Content-Type: application/json
...
[JSON action result value]
The structure of the action result value (if any) is determined by
the server implementation. If version control is implemented for a
Bryan Expires August 7, 2012 [Page 9]
Internet-Draft HTTP JSON Resource February 2012
given resource, the server MAY expose the updated resource version in
the ETag header of the response.
6. Request Context
A server MAY require some form of request context be established by
the client prior to allowing access to resources. How such context
is established, persisted and transmitted is out of the scope of this
convention, and SHOULD be specified by the server implementation.
If inadequate request context has been established, the server SHOULD
indicate this with a 401 Unauthorized error status code, unless there
is another means of indicating such which is consistent with the
required request context.
7. Access Control
The server implementation MAY enforce access control policies that
restrict what resources a client can access and/or on what JSON
values within each resource may be accessed.
If the necessary context has been established (including no context
at all) but such context does not permit the requested access to a
resource, the server SHOULD indicate this with a 403 Forbidden error
status code and a detail message describing the nature of the access
denial.
The server implementation MAY amend representations of resources to
conform to access control policies, and SHOULD specify under what
conditions such amendments are applied.
8. Resource Validation
The server MAY enforce validation rules on resource representations
provided by the client. If such a validation fails, the server
SHOULD indicate this with a 403 Forbidden error status code and a
detail message describing the nature of the validation failure.
9. Resource Metadata
Most responses to requests contain metadata about the resource being
accessed. The metadata is included an HTTP ETag response header as
well as members within a JSON object resource representation,
including a JSON object specifically intended to contain only
Bryan Expires August 7, 2012 [Page 10]
Internet-Draft HTTP JSON Resource February 2012
metadata (referred to within this document as a "resource metadata
object").
9.1. Header
ETag
The current version of a resource, if version control is implemented
for the resource.
9.2. Object Members
"_id": string, required
The identifier of the resource, relative to the collection it is a
member of.
"_rev": string, optional
The current version of the resource, if version control is
implemented for the resource.
10. Error Response
In the event of an error, a 4xx or 5xx HTTP status code SHOULD BE
expressed in the response, with an entity body containing an error
object adhering to the following structure:
{
"error": number,
"reason": string,
"detail": string
}
10.1. Members
"error": number, required
The value provided SHOULD coincide with the status code provided in
the HTTP response.
"reason": string, optional
A short reason phrase of the error.
"detail": string, optional
The detail message of the error.
11. Modifying a Resource Identifier
The server MAY allow the update and/or patch operations to modify the
Bryan Expires August 7, 2012 [Page 11]
Internet-Draft HTTP JSON Resource February 2012
identifier of a resource within the collection if the resource has a
JSON object representation. If such modification is disallowed, the
server SHOULD respond with a 403 Forbidden status code.
To indicate a request to modify the resource identifier, the "_id"
metadata member should be included in the request entity and differ
from the existing resource identifier in the Request-URI.
If the server successfully modifies the resource identifier, instead
of responding with a 200 OK status code, the server MUST respond with
a 201 Created status code, with a Location header containing the URI
of the newly created resource.
If there is already a resource with the requested identifier, the
server MUST respond with a 409 Conflict status code indicating it
could not be modified. If the server rejects the identifier as
invalid, the server SHOULD respond with a 403 Forbidden status code.
12. IANA Considerations
This document has no IANA actions.
13. Security Considerations
TBD.
14. Acknowledgements
The following individuals contributed ideas, feedback and wording,
which contributed to the content of this specification:
Alin Brici, Andi Egloff.
This convention was influenced by various projects that expose HTTP-
based access APIs, especially those that managed JSON-based
representations, notably CouchDB.
15. Normative References
[New-Status]
Nottingham, M. and R. Fielding, "Additional HTTP Status
Codes", October 2011, <http://tools.ietf.org/html/
draft-nottingham-http-new-status-03>.
Bryan Expires August 7, 2012 [Page 12]
Internet-Draft HTTP JSON Resource February 2012
[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.
[RFC4627] Crockford, D., "The application/json Media Type for
JavaScript Object Notation (JSON)", RFC 4627, July 2006.
[RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP",
RFC 5789, March 2010.
[URI-Template]
Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
and D. Orchard, "URI Template", September 2011,
<http://tools.ietf.org/html/
draft-gregorio-uritemplate-07>.
Appendix A. Examples
TBD.
Author's Address
Paul C. Bryan (editor)
ForgeRock
Phone: +1 604 783 1481
Email: pbryan@anode.ca
Bryan Expires August 7, 2012 [Page 13]