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/