idnits 2.17.1 draft-nottingham-json-home-01.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 (July 5, 2012) is 4311 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p6-cache-19 ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p4-conditional-19 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p5-range-19 == Outdated reference: A later version (-18) exists of draft-snell-http-prefer-12 -- Obsolete informational reference (is this intentional?): RFC 4288 (Obsoleted by RFC 6838) Summary: 2 errors (**), 0 flaws (~~), 5 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Nottingham 3 Internet-Draft Rackspace 4 Intended status: Informational July 5, 2012 5 Expires: January 6, 2013 7 Home Documents for HTTP APIs 8 draft-nottingham-json-home-01 10 Abstract 12 This document proposes a "home document" format for non-browser HTTP 13 clients. 15 Status of this Memo 17 This Internet-Draft is submitted in full conformance with the 18 provisions of BCP 78 and BCP 79. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF). Note that other groups may also distribute 22 working documents as Internet-Drafts. The list of current Internet- 23 Drafts is at http://datatracker.ietf.org/drafts/current/. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress." 30 This Internet-Draft will expire on January 6, 2013. 32 Copyright Notice 34 Copyright (c) 2012 IETF Trust and the persons identified as the 35 document authors. All rights reserved. 37 This document is subject to BCP 78 and the IETF Trust's Legal 38 Provisions Relating to IETF Documents 39 (http://trustee.ietf.org/license-info) in effect on the date of 40 publication of this document. Please review these documents 41 carefully, as they describe your rights and restrictions with respect 42 to this document. Code Components extracted from this document must 43 include Simplified BSD License text as described in Section 4.e of 44 the Trust Legal Provisions and are provided without warranty as 45 described in the Simplified BSD License. 47 Table of Contents 49 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 50 2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 3 51 3. JSON Home Documents . . . . . . . . . . . . . . . . . . . . . 3 52 4. Resource Objects . . . . . . . . . . . . . . . . . . . . . . . 5 53 4.1. Resolving Templated Links . . . . . . . . . . . . . . . . 5 54 5. Resource Hints . . . . . . . . . . . . . . . . . . . . . . . . 6 55 5.1. allow . . . . . . . . . . . . . . . . . . . . . . . . . . 7 56 5.2. representations . . . . . . . . . . . . . . . . . . . . . 7 57 5.3. accept-patch . . . . . . . . . . . . . . . . . . . . . . . 7 58 5.4. accept-post . . . . . . . . . . . . . . . . . . . . . . . 7 59 5.5. accept-put . . . . . . . . . . . . . . . . . . . . . . . . 7 60 5.6. accept-ranges . . . . . . . . . . . . . . . . . . . . . . 8 61 5.7. prefer . . . . . . . . . . . . . . . . . . . . . . . . . . 8 62 5.8. docs . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 63 5.9. precondition-req . . . . . . . . . . . . . . . . . . . . . 8 64 5.10. status . . . . . . . . . . . . . . . . . . . . . . . . . . 8 65 6. Creating and Serving Home Documents . . . . . . . . . . . . . 8 66 6.1. Managing Change in Home Documents . . . . . . . . . . . . 9 67 6.2. Evolving and Mixing APIs with Home Documents . . . . . . . 9 68 6.3. Documenting APIs that use Home Documents . . . . . . . . . 10 69 7. Consuming Home Documents . . . . . . . . . . . . . . . . . . . 10 70 8. Security Considerations . . . . . . . . . . . . . . . . . . . 10 71 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 72 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 73 10.1. Normative References . . . . . . . . . . . . . . . . . . . 11 74 10.2. Informative References . . . . . . . . . . . . . . . . . . 11 75 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 12 76 Appendix B. Frequently Asked Questions . . . . . . . . . . . . . 12 77 B.1. Why not Microformats? . . . . . . . . . . . . . . . . . . 12 78 B.2. What about authentication? . . . . . . . . . . . . . . . . 12 79 B.3. What about 'Faults' (i.e., errors)? . . . . . . . . . . . 12 80 B.4. How Do I find the XML Schema / JSON Schema / etc. for 81 a particular media type? . . . . . . . . . . . . . . . . . 13 82 Appendix C. Open Issues . . . . . . . . . . . . . . . . . . . . . 13 83 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 13 85 1. Introduction 87 There is an emerging preference for non-browser Web applications 88 (colloquially, "HTTP APIs") to use a link-driven approach to their 89 interactions to assure loose coupling, thereby enabling extensibility 90 and API evolution. 92 This is based upon experience with previous APIs that specified 93 static URI paths (such as 94 "http://api.example.com/v1.0/widgets/abc123/properties") have 95 resulted in brittle, tight coupling between clients and servers. 97 Sometimes, these APIs were documented by a document format like 98 WADL [1] that is used as a design time description; i.e., the URIs 99 and other information they describe are "baked into" client 100 implementations. 102 In contrast, a "follow your nose" API advertises the resources 103 available to clients using link relations [RFC5988] and the formats 104 they support using internet media types [RFC4288]. A client can then 105 decide - at run time - which resources to interact with based upon 106 its capabilities (as described by link relations), and the server can 107 safely add new resources and formats without disturbing clients that 108 are not yet aware of them. 110 As such, the client needs to be able to discover this information 111 quickly and efficiently use it to interact with the server. Just as 112 with a human-targeted home page for a site, we can create a "home 113 document" for a HTTP API that describes it to non-browser clients. 115 Of course, an HTTP API might use any format to do so; however, there 116 are advantages to having a standard home document format. This 117 specification suggests one for consideration, using the JSON format 118 [RFC4627]. 120 2. Requirements 122 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 123 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 124 document are to be interpreted as described in [RFC2119]. 126 3. JSON Home Documents 128 A JSON Home Document uses the format described in [RFC4627] and has 129 the media type "application/json-home". 131 Its content consists of a root object with a "resources" property, 132 whose names are link relation types (as defined by [RFC5988]), and 133 values are Resource Objects, defined below. 135 For example: 137 GET / HTTP/1.1 138 Host: example.org 139 Accept: application/json-home 141 HTTP/1.1 200 OK 142 Content-Type: application/json-home 143 Cache-Control: max-age=3600 144 Connection: close 146 { 147 "resources": { 148 "http://example.org/rel/widgets": { 149 "href": "/widgets/" 150 }, 151 "http://example.org/rel/widget": { 152 "href-template": "/widgets/{widget_id}", 153 "href-vars": { 154 "widget_id": "http://example.org/param/widget" 155 }, 156 "hints": { 157 "allow": ["GET", "PUT", "DELETE", "PATCH"], 158 "representations": ["application/json"], 159 "accept-patch": ["application/json-patch"], 160 "accept-post": ["application/xml"], 161 "accept-ranges": ["bytes"] 162 } 163 } 164 } 165 } 167 Here, we have a home document that links to a resource, "/widgets/" 168 with the relation "http://example.org/rel/widgets". It also links to 169 an undefined number of resources with the relation type 170 "http://example.org/rel/widget" using a URI Template [RFC6570], along 171 with a mapping of several identifiers to specific variables for use 172 in that template. 174 It also gives several hints about interacting with the latter 175 "widget" resources, including the HTTP methods usable with them, the 176 patch formats they accept, and the fact that they support partial 177 requests [I-D.ietf-httpbis-p5-range] using the "bytes" range- 178 specifier. 180 It gives no such hints about the "widgets" resource. This does not 181 mean that it (for example) doesn't support any HTTP methods; it means 182 that the client will need to discover this by interacting with the 183 resource, and/or examining the documentation for its link relation 184 type. 186 4. Resource Objects 188 A Resource Object links to resources of the defined type using one of 189 two mechanisms; either a direct link (in which case there is exactly 190 one resource of that relation type associated with the API), or a 191 templated link, in which case there are zero to many such resources. 193 Resource Objects MUST have only and exactly one of the "href" and 194 "href-template" properties. 196 Direct links are indicated with an "href" property, whose value is a 197 URI [RFC3986]. 199 Templated links are indicated with an "href-template" property, whose 200 value is a URI Template [RFC6570]. When "href-template" is present, 201 the Resource Object MUST have a "href-vars" property; see "Resolving 202 Templated Links". 204 In both forms, the links that "href" and "href-template" refer to are 205 URI-references [RFC3986] whose base URI is that of the JSON Home 206 Document itself. 208 Resource Objects MAY also have a "hints" property, whose value is an 209 object that uses named Resource Hints as its properties. 211 4.1. Resolving Templated Links 213 A URI can be derived from a Templated Link by treating the "href- 214 template" value as a Level 3 URI Template [RFC6570], using the "href- 215 vars" property to fill the template. 217 The "href-vars" property, in turn, is an object that acts as a 218 mapping between variable names available to the template and absolute 219 URIs that are used as global identifiers for the semantics and syntax 220 of those variables. 222 For example, given the following Resource Object: 224 "http://example.org/rel/widget": { 225 "href-template": "/widgets/{widget_id}", 226 "href-vars": { 227 "widget_id": "http://example.org/param/widget" 228 }, 229 "hints": { 230 "allow": ["GET", "PUT", "DELETE", "PATCH"], 231 "representations": ["application/json"], 232 "accept-patch": ["application/json-patch"], 233 "accept-post": ["application/xml"], 234 "accept-ranges": ["bytes"] 235 } 236 } 238 If you understand that "http://example.org/param/widget" is an 239 numeric identifier for a widget (perhaps by dereferencing that URL 240 and reading the documentation), you can then find the resource 241 corresponding to widget number 12345 at 242 "http://example.org/widgets/12345" (assuming that the Home Document 243 is located at "http://example.org/"). 245 5. Resource Hints 247 Resource hints allow clients to find relevant information about 248 interacting with a resource beforehand, as a means of optimising 249 communications, as well as advertising available behaviours (e.g., to 250 aid in laying out a user interface for consuming the API). 252 Hints are just that - they are not a "contract", and are to only be 253 taken as advisory. The runtime behaviour of the resource always 254 overrides hinted information. 256 For example, a resource might hint that the PUT method is allowed on 257 all "widget" resources. This means that generally, the user has the 258 ability to PUT to a particular resource, but a specific resource 259 could reject a PUT based upon access control or other considerations. 260 More fine-grained information might be gathered by interacting with 261 the resource (e.g., via a GET), or by another resource "containing" 262 it (such as a "widgets" collection). 264 This specification defines a set of common hints, based upon 265 information that's discoverable by directly interacting with 266 resources. A future draft will explain how to define new hints. 268 5.1. allow 270 Hints the HTTP methods that the current client will be able to use to 271 interact with the resource; equivalent to the Allow HTTP response 272 header. 274 Content MUST be an array of strings, containing HTTP methods. 276 5.2. representations 278 Hints the representation types that the resource produces and 279 consumes, using the GET and PUT methods respectively, subject to the 280 'allow' hint. 282 Content MUST be an array of strings, containing media types. 284 5.3. accept-patch 286 Hints the PATCH request formats [RFC5789] accepted by the resource 287 for this client; equivalent to the Accept-Patch HTTP response header. 289 Content MUST be an array of strings, containing media types. 291 When this hint is present, "PATCH" SHOULD be listed in the "allow" 292 hint. 294 5.4. accept-post 296 Hints the POST request formats accepted by the resource for this 297 client. 299 Content MUST be an array of strings, containing media types. 301 When this hint is present, "POST" SHOULD be listed in the "allow" 302 hint. 304 5.5. accept-put 306 Hints the PUT request formats accepted by the resource for this 307 client. 309 Content MUST be an array of strings, containing media types. If 310 absent, a client MAY assume that any format indicated by the 311 'representations' hint is acceptable in a PUT. 313 When this hint is present, "PUT" SHOULD be listed in the "allow" 314 hint. 316 5.6. accept-ranges 318 Hints the range-specifiers available to the client for this resource; 319 equivalent to the Accept-Ranges HTTP response header 320 [I-D.ietf-httpbis-p5-range]. 322 Content MUST be an array of strings, containing HTTP range- 323 specifiers. 325 5.7. prefer 327 Hints the preferences [I-D.snell-http-prefer] supported by the 328 resource. Note that, as per that specifications, a preference can be 329 ignored by the server. 331 Content MUST be an array of strings, contain preferences. 333 5.8. docs 335 Hints the location for human-readable documentation for the relation 336 type of the resource. 338 Content MUST be a string containing an absolute-URI [RFC3986] 339 referring to documentation that SHOULD be in HTML format. 341 5.9. precondition-req 343 Hints that the resource requires state-changing requests (e.g., PUT, 344 PATCH) to include a precondition, as per 345 [I-D.ietf-httpbis-p4-conditional], to avoid conflicts due to 346 concurrent updates. 348 Content MUST be an array of strings, with possible values "etag" and 349 "last-modified" indicating type type of precondition expected. 351 5.10. status 353 Hints the status of the resource. 355 Content MUST be a string; possible values are: 357 o "deprecated" - indicates that use of the resource is not 358 recommended, but it can still be used. 360 6. Creating and Serving Home Documents 362 When making a home document available, there are a few things to keep 363 in mind: 365 o A home document is best located at a memorable URI, because its 366 URI will effectively become the URI for the API itself to clients. 367 o Home documents can be personalised, just as "normal" home pages 368 can. For example, you might advertise different URIs, and/or 369 different kinds of link relations, depending on the client's 370 identity. 371 o Home documents SHOULD be assigned a freshness lifetime (e.g., 372 "Cache-Control: max-age=3600") so that clients can cache them, to 373 avoid having to fetch it every time the client interacts with the 374 service. 375 o Custom link relation types, as well as the URIs for variables, 376 should lead to documentation for those constructs. 378 6.1. Managing Change in Home Documents 380 The URIs used in home documents MAY change over time. However, 381 changing them can cause issues for clients that are relying on cached 382 home documents containing old links. 384 To mitigate these risks, servers changing links SHOULD consider: 386 o Reducing the freshness lifetime of home documents before a link 387 change, so that clients are less likely to refer to an "old" 388 document 389 o Assure that they handle requests for the "old" URIs appropriately; 390 e.g., with a 404 Not Found, or by redirecting the client to the 391 new URI. 392 o Alternatively, considering the "old" and "new" URIs as equally 393 valid references for an "overlap" period. 395 Generally, servers ought not to change URIs without good cause. 397 6.2. Evolving and Mixing APIs with Home Documents 399 Using home documents affords the opportunity to change the "shape" of 400 the API over time, without breaking old clients. 402 This includes introducing new functions alongside the old ones - by 403 adding new link relation types with corresponding resource objects - 404 as well as adding new template variables, media types, and so on. 406 It's important to realise that a home document can serve more than 407 one "API" at a time; by listing all relevant relation types, it can 408 effectively "mix" different APIs, allowing clients to work with 409 different resources as they see fit. 411 6.3. Documenting APIs that use Home Documents 413 Another use case for "static" API description formats like WSDL and 414 WADL is to generate documentation for the API from them. 416 An API that uses the home document format correctly won't have a need 417 to do so, provided that the link relation types and media types it 418 uses are well-documented already. 420 7. Consuming Home Documents 422 Clients might use home documents in a variety of ways. 424 In the most common case - actually consuming the API - the client 425 will scan the Resources Object for the link relation(s) that it is 426 interested in, and then to interact with the resource(s) referred to. 427 Resource Hints can be used to optimise communication with the client, 428 as well as to inform as to the permissible actions (e.g., whether PUT 429 is likely to be supported). 431 Note that the home document is a "living" document; it does not 432 represent a "contract", but rather is expected to be inspected before 433 each interaction. In particular, links from the home document MUST 434 NOT be assumed to be valid beyond the freshness lifetime of the home 435 document, as per HTTP's caching model [I-D.ietf-httpbis-p6-cache]. 437 As a result, clients SHOULD cache the home document (as per 438 [I-D.ietf-httpbis-p6-cache]), to avoid fetching it before every 439 interaction (which would otherwise be required). 441 Likewise, a client encountering a 404 Not Found on a link SHOULD 442 obtain a fresh copy of the home document, to assure that it is up-to- 443 date. 445 8. Security Considerations 447 TBD 449 9. IANA Considerations 451 TBD 453 10. References 454 10.1. Normative References 456 [I-D.ietf-httpbis-p6-cache] 457 Fielding, R., Lafon, Y., Nottingham, M., and J. Reschke, 458 "HTTP/1.1, part 6: Caching", 459 draft-ietf-httpbis-p6-cache-19 (work in progress), 460 March 2012. 462 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 463 Requirement Levels", BCP 14, RFC 2119, March 1997. 465 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 466 Resource Identifier (URI): Generic Syntax", STD 66, 467 RFC 3986, January 2005. 469 [RFC4627] Crockford, D., "The application/json Media Type for 470 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 472 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 474 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 475 and D. Orchard, "URI Template", RFC 6570, March 2012. 477 10.2. Informative References 479 [I-D.ietf-httpbis-p4-conditional] 480 Fielding, R., Lafon, Y., and J. Reschke, "HTTP/1.1, part 481 4: Conditional Requests", 482 draft-ietf-httpbis-p4-conditional-19 (work in progress), 483 March 2012. 485 [I-D.ietf-httpbis-p5-range] 486 Fielding, R., Lafon, Y., and J. Reschke, "HTTP/1.1, part 487 5: Range Requests and Partial Responses", 488 draft-ietf-httpbis-p5-range-19 (work in progress), 489 March 2012. 491 [I-D.snell-http-prefer] 492 Snell, J., "Prefer Header for HTTP", 493 draft-snell-http-prefer-12 (work in progress), 494 February 2012. 496 [RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and 497 Registration Procedures", BCP 13, RFC 4288, December 2005. 499 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 500 RFC 5789, March 2010. 502 URIs 504 [1] 506 [2] 508 Appendix A. Acknowledgements 510 Thanks to Mike Amundsen, Bill Burke, Graham Klyne, Leif Hedstrom, and 511 Jeni Tennison for their suggestions and feedback. 513 Appendix B. Frequently Asked Questions 515 B.1. Why not Microformats? 517 Browser-centric Web applications use HTML as their representation 518 format of choice. While it is possible to augment HTML for non- 519 browser clients (using techniques like Microformats [2] ), a few 520 issues become evident when doing so: 522 o HTML has a very forgiving syntax. While this is appropriate for 523 browsers (especially considering that there are many million HTML 524 authors in the world), it makes for a less-than-precise language 525 for machines, resulting in both overhead (parsing and 526 transmission) as well as lack of precision. 527 o HTML is presentation-centric, making it tempting to reformat it 528 from time to time, to improve the "look and feel" of a page. 529 However, doing so can cause comparatively brittle non-browser 530 clients to lose their understanding of the content's semantics, 531 unless very careful controls are in place. 533 Because of this, it's most practical to define a separate format, and 534 JSON is easily machine-readable, precise, and has a better chance of 535 being managed for stability. 537 B.2. What about authentication? 539 In HTTP, authentication is discoverable by interacting with the 540 resource (usually, by getting a 401 Unauthorized response status 541 code, along with one or more challenges). While the home document 542 could hint it, this isn't yet done, to avoid possible security 543 complications. 545 B.3. What about 'Faults' (i.e., errors)? 547 In HTTP, errors are conveyed by HTTP status codes. While this 548 specification could (and even may) allow enumeration of possible 549 error conditions, there's a concern that this will encourage 550 applications to define many such "faults", leading to tight coupling 551 between the application and its clients. 553 So, this is an area of possible future development; if any such 554 mechanism appears here, it's likely to be quite restricted. 556 B.4. How Do I find the XML Schema / JSON Schema / etc. for a particular 557 media type? 559 That isn't addressed by home documents. Ultimately, it's up to the 560 media type accepted and generated by resources to define and 561 constrain (or not) their syntax. 563 Appendix C. Open Issues 565 The following is a list of placeholders for open issues. 567 o Refining and extending representation formats - "application/xml", 568 for example, isn't enough. While a media type for every 569 representation is one answer, something like 'profile' might be 570 good too. 571 o Object for contact details - do we need an object that describes 572 who's running the API, etc? 573 o Defining new hints - guidance is needed on minting new hints. 574 Possibly a registry. 575 o Defining new top-level properties - how new ones are minted, 576 registry, etc. 577 o Defining new Resource Object properties - how new ones are minted, 578 registry, etc. 580 Author's Address 582 Mark Nottingham 583 Rackspace 585 Email: mnot@mnot.net 586 URI: http://www.mnot.net/