A Convention for HTTP Access to JSON-Based Resources
draft-pbryan-http-json-resource-02

Internet Engineering Task Force                            P. Bryan, Ed.
Internet-Draft                                                 ForgeRock
Intended status: Informational                         February 15, 2012
Expires: August 18, 2012

          A Convention for HTTP Access to JSON-Based Resources
                   draft-pbryan-http-json-resource-02

Abstract

   A convention for accessing JSON representations of resources via
   HTTP, promoting a uniform interface across multiple disparate
   resources and reuse of software components.

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 18, 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 18, 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.  Questions and Answers . . . . . . . . . . . . . . . . 13
   Appendix B.  Examples  . . . . . . . . . . . . . . . . . . . . . . 14
   Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 14

Bryan                    Expires August 18, 2012                [Page 2]
Internet-Draft             HTTP-JSON-Resource              February 2012

1.  Introduction

   JavaScript Object Notation (JSON) [RFC4627] is a common format for
   the representation of structured data.  Hypertext Transfer Protocol
   (HTTP) [RFC2616] is a common protocol for providing access to
   resources.

   This document codifies a convention for accessing JSON
   representations of resources via HTTP.  This promotes a uniform
   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 what identifiers
   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 SHOULD use
   preconditions when performing operations that modify such resources.

   The server expresses the resource version in an "ETag" response

Bryan                    Expires August 18, 2012                [Page 3]
Internet-Draft             HTTP-JSON-Resource              February 2012

   header, and the "_rev" metadata member in JSON object entity
   responses.  The client expresses resource version in the "If-Match"
   and "If-None-Match" precondition request headers.

   If a server implements version control for a resource, and the
   version specified by a client in a request does not match the current
   version of the resource, then the server SHOULD respond with a 412
   Precondition Failed error 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 MAY allow the operation, or
   indicate an error 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 of a given resource
   results in different versions.  Clients SHOULD treat a resource
   version provided by a server as opaque.

5.  Operations

   This convention provides a uniform set of operations, all of which
   are implemented through existing 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

   Using 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
   employ its own means of determining how to interpret the PUT method.

Bryan                    Expires August 18, 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

   Using 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.

Bryan                    Expires August 18, 2012                [Page 5]
Internet-Draft             HTTP-JSON-Resource              February 2012

   If the resulting representation of the resource is a JSON object, it
   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 employ 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 18, 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 all resources within a collection.  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 all the resources within a collection, only the
   collection location MUST be specified.

   If deleting all resources within a collection is not supported by the
   server implementation, the server SHOULD respond to such requests
   with a 403 Forbidden error status code.

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 does not have permission to modify resources in
   their entirety.

   The "patch" operation is performed using the HTTP PATCH method, per

Bryan                    Expires August 18, 2012                [Page 7]
Internet-Draft             HTTP-JSON-Resource              February 2012

   [RFC5789].  The supported patch document format(s) to apply the
   partial modifications are determined by the server implementation.

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 18, 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 18, 2012                [Page 9]
Internet-Draft             HTTP-JSON-Resource              February 2012

   resource the action is being performed on, 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 this condition 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 a sufficient request context has been established, 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 some detail in a response error object describing the nature of
   the denial of access.

   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 some
   detail in a response error object 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,

Bryan                    Expires August 18, 2012               [Page 10]
Internet-Draft             HTTP-JSON-Resource              February 2012

   including a JSON object specifically intended to contain only
   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 object
   that has minimally an "error" member.

   The server implementation MAY provide additional members in the error
   object, which provide additional context and description of the
   nature of the error.  Any such additional members SHOULD be specified
   by the server implementation.

   {
       "error": string,
       ...
   }

10.1.  Members

   "error": string, required
   A mnemonic error code that expresses the type of error that occurred.
   The error code values and their associated meanings SHOULD be
   specified by the server implementation.

11.  Modifying a Resource Identifier

   The server MAY allow the update and/or patch operations to modify the

Bryan                    Expires August 18, 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, Kornel Lesinski, Eve Maler, David Zuelke.

   This convention was influenced by various projects that expose HTTP-
   based data access interfaces, 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 18, 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.  Questions and Answers

   Why this convention?

      HTTP-based APIs seem to be repeatedly following similar patterns,
      but with enough differences to preclude common programmatic
      implementations.  The intent of this convention is to provide a
      basic set of rules upon which a more application-specific
      interface can be specified (principle: DRY).

   Is this a RESTful interface?

      This convention strays from a pure REST interface, as it
      prescribes a specific (JSON) representation for resources, and
      arguably fails to adhere to the principle of hypermedia as the
      engine of application state (HATEOS).

   What kind of interface is it?

      It may be better classified as a resource-oriented interface.  It
      establishes a uniform interface (set of operations), and maps
      between those operations and the standard methods provided by
      HTTP.

   Why are ETags coupled to resource version, not entity value?

      Entity tags in HTTP are intended to be used to compare two or more
      entities for the same resource.  Since this convention establishes

Bryan                    Expires August 18, 2012               [Page 13]
Internet-Draft             HTTP-JSON-Resource              February 2012

      an exclusive representation of the resource (JSON), entity tag
      should be safely associable with resource version.  RFC 2616
      provides some support for this view in section 14.24 by stating,
      "It is also used, on updating requests, to prevent inadvertent
      modification of the wrong version of a resource."

   Why are "query" and "action" operations abstract?

      Queries and actions are too domain-specific to allow any more
      specificity than is expressed in this convention.  Therefore, this
      convention does not attempt to define query/action semantics
      beyond the fact that they are parametric.

   Why not explicitly specify a patch format?

      JSON Patch was explicitly referenced in an earlier draft.
      However, it may not be the only applicable format, and there is no
      strong driver (at least to date) to mandate what patch document
      format should be supported.

Appendix B.  Examples

   TBD.

Author's Address

   Paul C. Bryan (editor)
   ForgeRock

   Phone: +1 604 783 1481
   Email: pbryan@anode.ca

Bryan                    Expires August 18, 2012               [Page 14]