idnits 2.17.1 draft-pbryan-http-json-resource-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (August 6, 2012) is 4281 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force P. Bryan, Ed. 3 Internet-Draft Salesforce.com 4 Intended status: Informational August 6, 2012 5 Expires: February 7, 2013 7 A Convention for HTTP Access to JSON Resources 8 draft-pbryan-http-json-resource-03 10 Abstract 12 A convention for accessing JSON representations of resources via 13 HTTP, promoting a uniform interface across multiple resources and 14 reuse of software components. 16 Status of this Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at http://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on February 7, 2013. 33 Copyright Notice 35 Copyright (c) 2012 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (http://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 51 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 3 52 3. Resources . . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 4. Version Control . . . . . . . . . . . . . . . . . . . . . . . 3 54 5. Operations . . . . . . . . . . . . . . . . . . . . . . . . . . 4 55 5.1. Create . . . . . . . . . . . . . . . . . . . . . . . . . . 4 56 5.2. Read . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 57 5.3. Update . . . . . . . . . . . . . . . . . . . . . . . . . . 6 58 5.4. Delete . . . . . . . . . . . . . . . . . . . . . . . . . . 7 59 5.5. Patch . . . . . . . . . . . . . . . . . . . . . . . . . . 7 60 5.6. Query . . . . . . . . . . . . . . . . . . . . . . . . . . 8 61 5.7. Action . . . . . . . . . . . . . . . . . . . . . . . . . . 9 62 6. Request Context . . . . . . . . . . . . . . . . . . . . . . . 10 63 7. Access Control . . . . . . . . . . . . . . . . . . . . . . . . 10 64 8. Resource Validation . . . . . . . . . . . . . . . . . . . . . 11 65 9. Resource Metadata . . . . . . . . . . . . . . . . . . . . . . 11 66 9.1. Header . . . . . . . . . . . . . . . . . . . . . . . . . . 11 67 9.2. Object Members . . . . . . . . . . . . . . . . . . . . . . 11 68 10. Error Response . . . . . . . . . . . . . . . . . . . . . . . . 11 69 10.1. Members . . . . . . . . . . . . . . . . . . . . . . . . . 12 70 11. Modifying a Resource Identifier . . . . . . . . . . . . . . . 12 71 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 72 13. Security Considerations . . . . . . . . . . . . . . . . . . . 12 73 14. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 12 74 15. Normative References . . . . . . . . . . . . . . . . . . . . . 13 75 Appendix A. Questions and Answers . . . . . . . . . . . . . . . . 13 76 Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 14 77 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 14 79 1. Introduction 81 JavaScript Object Notation (JSON) [RFC4627] is a common format for 82 the representation of structured data. Hypertext Transfer Protocol 83 (HTTP) [RFC2616] is the standard protocol for providing access to 84 resources. 86 This document codifies a convention for accessing JSON 87 representations of resources via HTTP. This promotes a uniform 88 interface across multiple resources and reuse of conforming server 89 and client software components. 91 2. Conventions 93 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 94 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 95 document are to be interpreted as described in RFC 2119 [RFC2119]. 97 This document expresses the structure of Request-URIs in examples 98 using URI Template [RFC6570] syntax. 100 3. Resources 102 A resource accessed through this convention is represented as a JSON 103 value with an "application/json" (or derivative) Internet media type. 105 An accessible resource is a member of a collection of resources. A 106 collection of resources MUST have a unique location, which is 107 expressed as a part of the Request-URI of HTTP requests. The server 108 implementation determines the location of a resource collection. 110 Each resource MUST have a unique identifier within a collection. The 111 server implementation MAY establish restrictions on what identifiers 112 can be used, and reject requests that have identifiers that do not 113 conform with a 403 Forbidden status code. 115 4. Version Control 117 A server MAY implement version control for resources, and use it as 118 the basis of an optimistic concurrency control mechanism. If version 119 control is implemented for a given resource, the server MUST expose 120 the resource version in responses, and clients SHOULD use 121 preconditions when performing operations that modify such resources. 123 The server expresses the resource version in an "ETag" response 124 header, and the "_rev" metadata member in JSON object entity 125 responses. The client expresses resource version in the "If-Match" 126 and "If-None-Match" precondition request headers. 128 If a server implements version control for a resource, and the 129 version specified by a client in a request does not match the current 130 version of the resource, then the server SHOULD respond with a 412 131 Precondition Failed error status code. 133 If a server implements version control for a resource and the 134 resource version is not specified by a client for an operation that 135 modifies the resource, the server MAY allow the operation, or reject 136 it with a 428 Precondition Required status code, per [RFC6585]. 138 The server implementation determines how a resource version is 139 computed; it MUST ensure that different values of a given resource 140 results in different versions. Clients SHOULD treat a resource 141 version provided by a server as opaque. 143 5. Operations 145 This convention provides a uniform set of operations, all of which 146 are implemented through existing HTTP methods. The operations are: 147 create, read, update, delete, patch, query, and action. The server 148 MAY conditionally implement any operation. 150 5.1. Create 152 The "create" operation allows a client to create a new resource in a 153 collection. A resource is created in one of two ways: if the client 154 is requesting a specific identifier, then the resource is created via 155 the HTTP PUT method; if the server is to select its own identifier, 156 then the resource is created via the POST method. The PUT method 157 SHOULD be preferred over POST. 159 5.1.1. PUT Request 161 Using the PUT method, the identifier of the resource to create is 162 specified in the Request-URI of the HTTP request. The server MAY 163 override the requested identifier of the resource and select a 164 suitable identifier of its own. 166 To unambiguously request resource creation, the "If-None-Match" 167 header MUST contain the value "*". If no precondition header 168 unambiguously requests resource creation or update, the server MAY 169 employ its own means of determining how to interpret the PUT method. 171 PUT /{collection}/{id} HTTP/1.1 172 Content-Type: application/json 173 If-None-Match: * 174 ... 176 [JSON representation of resource to create] 178 5.1.2. POST Request 180 Using the POST method, the identifier of the resource is not 181 specified. The Request-URI of the request MUST NOT contain a query 182 component, to distinguish it from an action operation. The server 183 MUST select a suitable identifier for the created resource. 185 POST /{collection} HTTP/1.1 186 Content-Type: application/json 187 ... 189 [Resource representation] 191 5.1.3. Response 193 HTTP/1.1 201 Created 194 Content-Type: application/json 195 Location: [location of resource] 196 ETag: "[resource version]" 197 ... 199 [Resource metadata object] 201 The "Location" header field contains a URI that identifies the newly 202 created resource. The optional "ETag" header field contains the 203 version of the newly created resource. The resource metadata object 204 also contains the identifier and optional version of the newly 205 created resource. 207 If version control is implemented for a given resource, the server 208 MUST expose the new resource version in the ETag header of the 209 response. 211 5.2. Read 213 The "read" operation allows a client to read a representation of a 214 resource from the server. It is implemented using the HTTP GET 215 method. The client MUST NOT include a query component in the 216 Request-URI, to distinguish it from a query operation. 218 If the resulting representation of the resource is a JSON object, it 219 SHOULD contain the JSON "_id" member, and also the "_rev" member if 220 resource version is supported by the server implementation. 222 5.2.1. Request 224 GET /{collection}/{id} HTTP/1.1 225 ... 227 5.2.2. Response 229 HTTP/1.1 200 OK 230 Content-Type: application/json 231 ETag: "[resource version]" 232 ... 234 [Resource representation] 236 If version control is implemented for a given resource, the server 237 MUST expose the resource version in the ETag header of the response. 239 5.3. Update 241 The "update" operation allows a client to update the representation 242 of a resource on the server. It is performed using the HTTP PUT 243 method. To cause the PUT method to unambiguously request a resource 244 update, the "If-Match" header MUST contain the current version of the 245 resource. If no precondition header unambiguously requests resource 246 creation or update, the server MAY employ its own means of 247 determining how to interpret the PUT method. 249 5.3.1. Request 251 PUT /{collection}/{id} HTTP/1.1 252 Content-Type: application/json 253 If-Match: "[resource version]" 254 ... 256 [Resource representation] 258 5.3.2. Response 260 HTTP/1.1 200 OK 261 Content-Type: application/json 262 ETag: "[resource version]" 263 ... 265 [Resource metadata object] 267 If version control is implemented for a given resource, the server 268 MUST expose the updated resource version in the ETag header of the 269 response. 271 5.4. Delete 273 The "delete" operation allows a client to delete a resource, or 274 optionally an all resources within a collection. It is performed 275 using the HTTP DELETE method. 277 To delete a single resource, both the collection location and 278 resource identifier MUST be specified in the Request-URI of the HTTP 279 request. To delete all the resources within a collection, the 280 collection location MUST be specified. 282 If deleting all resources within a collection is not supported by the 283 server implementation, the server SHOULD respond to such requests 284 with a 403 Forbidden error status code. 286 5.4.1. Request 288 DELETE /{collection}/{id} HTTP/1.1 289 If-Match: "[resource version]" 290 ... 292 5.4.2. Response 294 HTTP/1.1 204 No Content 295 ... 297 5.5. Patch 299 The "patch" operation allows a client to apply a set of partial 300 modifications to a resource on the server. This is particularly 301 useful if the client does not have permission to modify resources in 302 their entirety. 304 The "patch" operation is performed using the HTTP PATCH method, per 306 [RFC5789]. The supported patch document format(s) to apply the 307 partial modifications are determined by the server implementation. 309 5.5.1. Request 311 PATCH /{collection}/{id} HTTP/1.1 312 If-Match: "[resource version]" 313 ... 315 [Patch document content] 317 5.5.2. Response 319 HTTP/1.1 200 OK 320 Content-Type: application/json 321 ETag: "[resource version]" 322 ... 324 [Resource metadata object] 326 If version control is implemented for a given resource, the server 327 MUST expose the updated resource version in the ETag header of the 328 response. 330 5.6. Query 332 The "query" operation performs a parametric query of a resource or 333 collection, and responds with a corresponding result. The execution 334 of a query MUST NOT incur side effects. It is implemented using the 335 HTTP GET method. The client MUST include a query component in the 336 Request-URI to distinguish it from a read operation. 338 To query a single resource, both the collection location and resource 339 identifier MUST be specified in the Request-URI of the HTTP request. 340 To query an entire collection, the collection location MUST be 341 specified. 343 5.6.1. Request 345 GET /{collection}/{id}?{query} HTTP/1.1 346 ... 348 5.6.2. Response 350 HTTP/1.1 200 OK 351 Content-Type: application/json 352 ... 354 [Query result value] 356 The structure of the query result value is determined by the server 357 implementation. 359 5.7. Action 361 The "action" operation performs a parametric action on a resource or 362 collection, and responds with an optional result. The execution of 363 an action MAY incur side effects. 365 The operation is implemented via the HTTP POST request. The Request- 366 URI MUST contain a query component, to distinguish it from a create 367 operation. The request MAY include an entity body. 369 To perform an action on a single resource, both the collection 370 location and resource identifier MUST be specified in the Request- 371 URI. To perform an action on an entire collection, the collection 372 location MUST be specified. 374 If the response contains a result value, then the server SHOULD 375 respond with a 200 OK status code; otherwise it SHOULD respond with a 376 204 No Content status code. 378 5.7.1. Request (with entity body) 380 POST /{component}/{id}?{query} HTTP/1.1 381 Content-Type: [entity body content type] 382 ... 384 [Entity body] 386 5.7.2. Request (without entity body) 388 POST /{component}/{id}?{query} HTTP/1.1 389 ... 391 5.7.3. Response 393 HTTP/1.1 200 OK 394 Content-Type: application/json 395 ... 397 [JSON action result] 399 If the response contains a result, then the server SHOULD respond 400 with a 200 OK status code; otherwise it SHOULD respond with a 204 No 401 Content status code. 403 The structure of the action response value (if any) is determined by 404 the server implementation. If version control is implemented for a 405 resource the action is being performed on, the server MAY expose the 406 updated resource version in the ETag header of the response. 408 6. Request Context 410 A server MAY require some form of request context be established by 411 the client prior to allowing access to resources. How such context 412 is established, persisted and transmitted is out of the scope of this 413 convention, and SHOULD be specified by the server implementation. 415 If inadequate request context has been established, the server SHOULD 416 indicate this with a 401 Unauthorized error status code, unless there 417 is another means of indicating this condition which is consistent 418 with the required request context. 420 7. Access Control 422 The server implementation MAY enforce access control policies that 423 restrict what resources a client can access and/or on what JSON 424 values within each resource may be accessed. 426 If a sufficient request context has been established, but such 427 context does not permit the requested access to a resource, the 428 server SHOULD reject such requests with a 403 Forbidden error status 429 code and some detail in a response error object describing the nature 430 of the rejection. 432 The server implementation MAY amend representations of resources to 433 conform to access control policies, and SHOULD specify under what 434 conditions such amendments are applied. 436 8. Resource Validation 438 The server MAY enforce validation rules on resource representations 439 provided by the client. If such a validation fails, the server 440 SHOULD indicate this with a 403 Forbidden error status code and some 441 detail in a response error object describing the nature of the 442 validation failure. 444 9. Resource Metadata 446 Most responses to requests contain metadata about the resource being 447 accessed. The metadata is included an HTTP ETag response header as 448 well as members within a JSON object resource representation, 449 including a JSON object specifically intended to contain only 450 metadata (referred to within this document as a "resource metadata 451 object"). 453 9.1. Header 455 ETag 456 The current version of a resource, if version control is implemented 457 for the resource. 459 9.2. Object Members 461 "_id": string, required 462 The identifier of the resource, relative to the collection it is a 463 member of. 465 "_rev": string, optional 466 The current version of the resource, if version control is 467 implemented for the resource. 469 10. Error Response 471 In the event of an error, a 4xx or 5xx HTTP status code SHOULD BE 472 included in the response, with an entity body containing a JSON 473 object that has minimally an "error" member. 475 The server implementation MAY provide additional members in the error 476 object, which provide additional context and description of the 477 nature of the error. Any such additional members SHOULD be specified 478 by the server implementation. 480 { 481 "error": string, 482 ... 483 } 485 10.1. Members 487 "error": string, required 488 A mnemonic error code that expresses the type of error that occurred. 489 The error code values and their associated meanings SHOULD be 490 specified by the server implementation. 492 11. Modifying a Resource Identifier 494 The server MAY allow the update and/or patch operations to modify the 495 identifier of a resource within the collection if the resource has a 496 JSON object representation. If such modification is disallowed, the 497 server SHOULD respond with a 403 Forbidden status code. 499 To indicate a request to modify the resource identifier, the "_id" 500 metadata member should be included in the request entity and differ 501 from the existing resource identifier in the Request-URI. 503 If the server successfully modifies the resource identifier, instead 504 of responding with a 200 OK status code, the server MUST respond with 505 a 201 Created status code, with a Location header containing the URI 506 of the newly created resource. 508 If there is already a resource with the requested identifier, the 509 server MUST respond with a 409 Conflict status code indicating it 510 could not be modified. If the server rejects the identifier as 511 invalid, the server SHOULD respond with a 403 Forbidden status code. 513 12. IANA Considerations 515 This document has no IANA actions. 517 13. Security Considerations 519 TBD. 521 14. Acknowledgements 523 The following individuals contributed ideas, feedback and wording to 524 this specification: 526 Alin Brici, Andi Egloff, Kornel Lesinski, Eve Maler, Ryder Ross, 527 David Zarlengo, David Zuelke. 529 This convention was influenced by various projects that expose HTTP- 530 based data access interfaces, especially those that managed JSON- 531 based representations, notably CouchDB. 533 15. Normative References 535 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 536 Requirement Levels", BCP 14, RFC 2119, March 1997. 538 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 539 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 540 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 542 [RFC4627] Crockford, D., "The application/json Media Type for 543 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 545 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 546 RFC 5789, March 2010. 548 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 549 and D. Orchard, "URI Template", RFC 6570, March 2012. 551 [RFC6585] Nottingham, M. and R. Fielding, "Additional HTTP Status 552 Codes", RFC 6585, April 2012. 554 Appendix A. Questions and Answers 556 Why this convention? 558 HTTP-based APIs seem to be repeatedly following similar patterns, 559 but with enough differences to preclude common programmatic 560 implementations. The intent of this convention is to provide a 561 basic set of rules upon which a more application-specific 562 interface can be specified (principle: DRY). 564 Is this a RESTful interface? 566 This convention strays from a pure REST interface, as it 567 prescribes a specific (JSON) representation for resources, and 568 arguably fails to adhere to the principle of hypermedia as the 569 engine of application state (HATEOS). 571 What kind of interface is it? 573 It may be better classified as a resource-oriented interface. It 574 establishes a uniform interface (set of operations), and maps 575 between those operations and the standard methods provided by 576 HTTP. 578 Why are ETags coupled to resource version, not entity value? 580 Entity tags in HTTP are intended to be used to compare two or more 581 entities for the same resource. Since this convention establishes 582 an exclusive representation of the resource (JSON), entity tag 583 should be safely associable with resource version. RFC 2616 584 provides support for this practice in section 14.24 by stating, 585 "It is also used, on updating requests, to prevent inadvertent 586 modification of the wrong version of a resource." 588 Why are "query" and "action" operations abstract? 590 Queries and actions are too domain-specific to allow any more 591 specificity than is expressed in this convention. Therefore, this 592 convention does not attempt to define query/action semantics 593 beyond the fact that they are parametric. 595 Appendix B. Examples 597 TBD. 599 Author's Address 601 Paul C. Bryan (editor) 602 Salesforce.com 604 Phone: +1 604 783 1481 605 Email: pbryan@anode.ca