idnits 2.17.1 draft-nottingham-json-home-00.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 (May 9, 2012) is 4363 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) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) -- Obsolete informational reference (is this intentional?): RFC 4288 (Obsoleted by RFC 6838) Summary: 3 errors (**), 0 flaws (~~), 1 warning (==), 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 May 9, 2012 5 Expires: November 10, 2012 7 Home Documents for HTTP APIs 8 draft-nottingham-json-home-00 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 November 10, 2012. 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-ranges . . . . . . . . . . . . . . . . . . . . . . 7 60 6. Creating and Serving Home Documents . . . . . . . . . . . . . 7 61 6.1. Managing Change in Home Documents . . . . . . . . . . . . 8 62 6.2. Evolving and Mixing APIs with Home Documents . . . . . . . 8 63 6.3. Documenting APIs that use Home Documents . . . . . . . . . 8 64 7. Consuming Home Documents . . . . . . . . . . . . . . . . . . . 9 65 8. Security Considerations . . . . . . . . . . . . . . . . . . . 9 66 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 67 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9 68 10.1. Normative References . . . . . . . . . . . . . . . . . . . 9 69 10.2. Informative References . . . . . . . . . . . . . . . . . . 10 70 Appendix A. Frequently Asked Questions . . . . . . . . . . . . . 10 71 A.1. Why not Microformats? . . . . . . . . . . . . . . . . . . 10 72 A.2. What about authentication? . . . . . . . . . . . . . . . . 11 73 A.3. What about "Faults" (i.e., errors)? . . . . . . . . . . . 11 74 A.4. How Do I find the XML Schema / JSON Schema / etc. for 75 a particular media type? . . . . . . . . . . . . . . . . . 11 76 Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . . 11 77 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 12 79 1. Introduction 81 There is an emerging preference for non-browser Web applications 82 (colloquially, "HTTP APIs") to use a link-driven approach to their 83 interactions to assure loose coupling, thereby enabling extensibility 84 and API evolution. 86 This is based upon experience with previous APIs which specified 87 static URI paths (such as 88 "http://api.example.com/v1.0/widgets/abc123/properties") have 89 resulted in brittle, tight coupling between clients and servers. 91 Sometimes, these APIs are documented by a document format like 92 WADL [1] that is used as a "design-time" description; i.e., the URIs 93 and other information they describe are "baked into" client 94 implementations. 96 In contrast, a "follow your nose" API advertises the resources 97 available to clients using link relations [RFC5988] and the formats 98 they support using internet media types [RFC4288]. A client can then 99 decide - at "run time" - which resources to interact with based upon 100 its capabilities (as described by link relations), and the server can 101 safely add new resources and formats without disturbing clients that 102 are not yet aware of them. 104 As such, the client needs to be able to discover this information 105 quickly and efficiently use it to interact with the server. Just as 106 with a human-targeted "home page" for a site, we can create a "home 107 document" for a HTTP API (often, at the same URI, found through 108 server-driven content negotiation) that describes it to non-browser 109 clients. 111 Of course, an HTTP API might use any format to do so; however, there 112 are advantages to having a standard home document format. This 113 specification suggests one for consideration, using the JSON format 114 [RFC4627]. 116 2. Requirements 118 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 119 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 120 document are to be interpreted as described in [RFC2119]. 122 3. JSON Home Documents 124 A JSON Home Document uses the format described in [RFC4627] and has 125 the media type "application/json-home". 127 Its content consists of a root object with a "resources" property, 128 whose names are link relation types (as defined by [RFC5988]), and 129 values are Resource Objects, defined below. 131 For example: 133 GET / HTTP/1.1 134 Host: example.org 135 Accept: application/json-home 137 HTTP/1.1 200 OK 138 Content-Type: application/json-home 139 Cache-Control: max-age=3600 140 Connection: close 142 { 143 "resources": { 144 "http://example.org/rel/widgets": { 145 "href": "/widgets/" 146 }, 147 "http://example.org/rel/widget": { 148 "href-template": "/widgets/{widget_id}", 149 "href-vars": { 150 "widget_id": "http://example.org/param/widget" 151 }, 152 "hints": { 153 "allow": ["GET", "PUT", "DELETE", "PATCH"], 154 "representations": ["application/json"], 155 "accept-patch": ["application/json-patch"], 156 "accept-post": ["application/xml"], 157 "accept-ranges": ["bytes"] 158 } 159 } 160 } 161 } 163 Here, we have a home document that links two a resource, "/widgets/" 164 with the relation "http://example.org/rel/widgets", and also links to 165 one or more with the relation type "http://example.org/rel/widget" 166 using a URI Template [RFC6570]. 168 It also gives several hints about interacting with the latter 169 "widget" resources, including the HTTP methods usable with them, the 170 patch formats they accept, and the fact that they support partial 171 requests [RFC2616] using the "bytes" range-specifier. 173 It gives no such hints about the "widgets" resource. This does not 174 mean that it (for example) doesn't support any HTTP methods; it means 175 that the client will need to discover this by interacting with the 176 resource, and/or examining the documentation for its link relation 177 type. 179 4. Resource Objects 181 A Resource Object links to resources of the defined type using one of 182 two mechanisms; either a direct link (in which case there is exactly 183 one resource of that relation type associated with the API), or a 184 templated link, in which case there are zero to many such resources. 186 Direct links are indicated with an "href" property, whose value is a 187 URI [RFC3986]. 189 Templated links are indicated with an "href-template" property, whose 190 value is a URI Template [RFC6570]. When "href-template" is present, 191 the Resource Object MUST have a "href-vars" property; see "Resolving 192 Templated Links". 194 Resource Objects MUST have exactly one of the "href" and "href-vars" 195 properties. 197 In both forms, the links that "href" and "href-template" refer to are 198 URI-references [RFC3986] whose base URI is that of the JSON Home 199 Document itself. 201 Resource Objects MAY also have a "hints" property, whose value is an 202 object that uses named Resource Hints as its properties. 204 4.1. Resolving Templated Links 206 A URI can be derived from a Templated Link by treating the "href- 207 template" value as a Level 3 URI Template [RFC6570], using the "href- 208 vars" property to fill the template. 210 The "href-vars" property, in turn, is an object that acts as a 211 mapping between variable names available to the template and absolute 212 URIs that are used as global identifiers for the semantics and syntax 213 of those variables. 215 For example, given the following Resource Object: 217 "http://example.org/rel/widget": { 218 "href-template": "/widgets/{widget_id}", 219 "href-vars": { 220 "widget_id": "http://example.org/param/widget" 221 }, 222 "hints": { 223 "allow": ["GET", "PUT", "DELETE", "PATCH"], 224 "representations": ["application/json"], 225 "accept-patch": ["application/json-patch"], 226 "accept-post": ["application/xml"], 227 "accept-ranges": ["bytes"] 228 } 229 } 231 If you understand that "http://example.org/param/widget" is an 232 numeric identifier for a widget (perhaps by dereferencing that URL 233 and reading the documentation), you can then find the resource 234 corresponding to widget number 12345 at 235 "http://example.org/widgets/12345" (assuming that the Home Document 236 is located at "http://example.org/"). 238 5. Resource Hints 240 Resource hints allow clients to find relevant information about 241 interacting with a resource beforehand, as a means of optimising 242 communications, as well as advertising available behaviours (e.g., to 243 aid in laying out a user interface for consuming the API). 245 Hints are just that - they are not a "contract", and are to only be 246 taken as advisory. The runtime behaviour of the resource always 247 overrides hinted information. 249 For example, a resource might hint that the PUT method is allowed on 250 all "widget" resources. this means that generally, the user has the 251 ability to PUT to a particular resource, but a specific resource may 252 reject a PUT based upon access control or other considerations. More 253 fine-grained information might be gathered by interacting with the 254 resource (e.g., via a GET), or by another resource "containing" it 255 (such as a "widgets" collection). 257 This specification defines a set of common hints, based upon 258 information that's discoverable by directly interacting with 259 resources. A future draft will explain how to define new hints. 261 5.1. allow 263 Hints the HTTP methods that the current client will be able to use to 264 interact with the resource; equivalent to the Allow HTTP response 265 header. 267 Content MUST be an array of strings, containing HTTP methods. 269 5.2. representations 271 Hints the representation types that the resource produces and 272 consumes, using the GET and PUT methods respectively, subject to the 273 'allow' hint. 275 Content MUST be an array of strings, containing media types. 277 5.3. accept-patch 279 Hints the PATCH request formats accepted by the resource for this 280 client; equivalent to the Accept-Patch HTTP response header. 282 Content MUST be an array of strings, containing media types. 284 5.4. accept-post 286 Hints the POST request formats accepted by the resource for this 287 client. 289 Content MUST be an array of strings, containing media types. 291 5.5. accept-ranges 293 Hints the range-specifiers available to the client for this resource; 294 equivalent to the Accept-Ranges HTTP response header. 296 Content MUST be an array of strings, containing HTTP range- 297 specifiers. 299 6. Creating and Serving Home Documents 301 When making a home document available, there are a few things to keep 302 in mind: 304 o A home document is best located at a memorable URI, because its 305 URI will effectively become the URI for the API itself to clients. 307 o Home documents can be personalised, just as "normal" home pages 308 can. For example, you might advertise different URIs, and/or 309 different kinds of link relations, depending on the client's 310 identity. 311 o Home documents SHOULD be assigned a freshness lifetime (e.g., 312 "Cache-Control: max-age=3600") so that clients can cache them, to 313 avoid having to fetch it every time the client interacts with the 314 service. 315 o Custom link relation types, as well as the URIs for variables, 316 should lead to documentation for those constructs. 318 6.1. Managing Change in Home Documents 320 The URIs used in home documents MAY change over time. However, 321 changing them can cause issues for clients that are relying on cached 322 home documents containing old links. 324 To mitigate these risks, servers changing links SHOULD consider: 326 o Reducing the freshness lifetime of home documents before a link 327 change, so that clients are less likely to refer to an "old" 328 document 329 o Assure that they handle requests for the "old" URIs appropriately; 330 e.g., with a 404 Not Found, or by redirecting the client to the 331 new URI. 332 o Alternatively, considering the "old" and "new" URIs as equally 333 valid references for an "overlap" period. 335 Generally, servers ought not to change URIs without good cause. 337 6.2. Evolving and Mixing APIs with Home Documents 339 Using home documents affords the opportunity to change the "shape" of 340 the API over time, without breaking old clients. 342 This includes introducing new functions alongside the old ones - by 343 adding new link relation types with corresponding resource objects - 344 as well as adding new template variables, media types, and so on. 346 It's important to realise that a home document can serve more than 347 one "API" at a time; by listing all relevant relation types, it can 348 effectively "mix" different APIs, allowing clients to work with 349 different resources as they see fit. 351 6.3. Documenting APIs that use Home Documents 353 Another use case for "static" API description formats like WSDL and 354 WADL is to generate documentation for the API from them. 356 An API that uses the home document format correctly won't have a need 357 to do so, provided that the link relation types and media types it 358 uses are well-documented already. 360 7. Consuming Home Documents 362 Clients might use home documents in a variety of ways. 364 In the most common case - actually consuming the API - the client 365 will scan the Resources Object for the link relation(s) that it is 366 interested in, and then to interact with the resource(s) referred to. 367 Resource Hints can be used to optimise communication with the client, 368 as well as to inform as to the permissible actions (e.g., whether PUT 369 is likely to be supported). 371 Note that the home document is a "living" document; it does not 372 represent a "contract", but rather is expected to be inspected before 373 each interaction. In particular, links from the home document MUST 374 NOT be assumed to be valid beyond the freshness lifetime of the home 375 document, as per HTTP's caching model [RFC2616]. 377 As a result, clients SHOULD cache the home document (as per 378 [RFC2616], to avoid fetching it before every interaction (which would 379 otherwise be required). 381 Likewise, a client encountering a 404 Not Found on a link SHOULD 382 obtain a fresh copy of the home document, to assure that it is up-to- 383 date. 385 8. Security Considerations 387 TBD 389 9. IANA Considerations 391 TBD 393 10. References 395 10.1. Normative References 397 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 398 Requirement Levels", BCP 14, RFC 2119, March 1997. 400 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 401 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 402 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 404 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 405 Resource Identifier (URI): Generic Syntax", STD 66, 406 RFC 3986, January 2005. 408 [RFC4627] Crockford, D., "The application/json Media Type for 409 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 411 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 413 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 414 and D. Orchard, "URI Template", RFC 6570, March 2012. 416 10.2. Informative References 418 [RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and 419 Registration Procedures", BCP 13, RFC 4288, December 2005. 421 URIs 423 [1] 425 [2] 427 Appendix A. Frequently Asked Questions 429 A.1. Why not Microformats? 431 Browser-centric Web applications use HTML as their representation 432 format of choice. While it is possible to augment HTML for non- 433 browser clients (using techniques like Microformats [2] ), a few 434 issues become evident when doing so: 436 o HTML has a very forgiving syntax. While this is appropriate for 437 browsers (especially considering that there are many million HTML 438 authors in the world), it makes for a less-than-precise language 439 for machines, resulting in both overhead (parsing and 440 transmission) as well as lack of precision. 441 o HTML is presentation-centric, making it tempting to reformat it 442 from time to time, to improve the "look and feel" of a page. 443 However, doing so can cause comparatively brittle non-browser 444 clients to lose their understanding of the content's semantics, 445 unless very careful controls are in place. 447 Because of this, it's most practical to define a separate format, and 448 JSON is easily machine-readable, precise, and has a better chance of 449 being managed for stability. 451 A.2. What about authentication? 453 In HTTP, authentication is discoverable by interacting with the 454 resource (usually, by getting a 401 Unauthorized response status 455 code, along with one or more challenges). While the home document 456 could hint it, this isn't yet done, to avoid possible security 457 complications. 459 A.3. What about "Faults" (i.e., errors)? 461 In HTTP, errors are conveyed by HTTP status codes. While this 462 specification could (and even may) allow enumeration of possible 463 error conditions, there's a concern that this will encourage 464 applications to define many such "faults", leading to tight coupling 465 between the application and its clients. 467 So, this is an area of possible future development; if any such 468 mechanism appears here, it's likely to be quite restricted. 470 A.4. How Do I find the XML Schema / JSON Schema / etc. for a particular 471 media type? 473 That isn't addressed by home documents. Ultimately, it's up to the 474 media type accepted and generated by resources to define and 475 constrain (or not) their syntax. 477 Appendix B. Open Issues 479 The following is a list of placeholders for open issues. 481 o Refining and extending representation formats - "application/xml", 482 for example, isn't enough. While a media type for every 483 representation is one answer, something like 'profile' might be 484 good too. 485 o Object for contact details - do we need an object that describes 486 who's running the API, etc? 487 o Defining new hints - guidance is needed on minting new hints. 488 Possibly a registry. 489 o Defining new top-level properties - how new ones are minted, 490 registry, etc. 491 o Defining new Resource Object properties - how new ones are minted, 492 registry, etc. 494 Author's Address 496 Mark Nottingham 497 Rackspace 499 Email: mnot@mnot.net 500 URI: http://www.mnot.net/