idnits 2.17.1
draft-nottingham-json-home-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 (May 8, 2013) is 3999 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-22
** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159)
** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126)
** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288)
== Outdated reference: A later version (-26) exists of
draft-ietf-httpbis-p4-conditional-22
== Outdated reference: A later version (-26) exists of
draft-ietf-httpbis-p5-range-22
== Outdated reference: A later version (-26) exists of
draft-ietf-httpbis-p7-auth-22
Summary: 3 errors (**), 0 flaws (~~), 5 warnings (==), 1 comment (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 Network Working Group M. Nottingham
3 Internet-Draft May 8, 2013
4 Intended status: Informational
5 Expires: November 9, 2013
7 Home Documents for HTTP APIs
8 draft-nottingham-json-home-03
10 Abstract
12 This document proposes a "home document" format for non-browser HTTP
13 clients.
15 Note to Readers
17 This draft should be discussed on the apps-discuss mailing list; see
18 [apps-discuss].
20 Status of this Memo
22 This Internet-Draft is submitted in full conformance with the
23 provisions of BCP 78 and BCP 79.
25 Internet-Drafts are working documents of the Internet Engineering
26 Task Force (IETF). Note that other groups may also distribute
27 working documents as Internet-Drafts. The list of current Internet-
28 Drafts is at http://datatracker.ietf.org/drafts/current/.
30 Internet-Drafts are draft documents valid for a maximum of six months
31 and may be updated, replaced, or obsoleted by other documents at any
32 time. It is inappropriate to use Internet-Drafts as reference
33 material or to cite them other than as "work in progress."
35 This Internet-Draft will expire on November 9, 2013.
37 Copyright Notice
39 Copyright (c) 2013 IETF Trust and the persons identified as the
40 document authors. All rights reserved.
42 This document is subject to BCP 78 and the IETF Trust's Legal
43 Provisions Relating to IETF Documents
44 (http://trustee.ietf.org/license-info) in effect on the date of
45 publication of this document. Please review these documents
46 carefully, as they describe your rights and restrictions with respect
47 to this document. Code Components extracted from this document must
48 include Simplified BSD License text as described in Section 4.e of
49 the Trust Legal Provisions and are provided without warranty as
50 described in the Simplified BSD License.
52 Table of Contents
54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
55 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3
56 2. JSON Home Documents . . . . . . . . . . . . . . . . . . . . . 3
57 3. Resource Objects . . . . . . . . . . . . . . . . . . . . . . . 5
58 3.1. Resolving Templated Links . . . . . . . . . . . . . . . . 6
59 4. Resource Hints . . . . . . . . . . . . . . . . . . . . . . . . 6
60 4.1. allow . . . . . . . . . . . . . . . . . . . . . . . . . . 7
61 4.2. formats . . . . . . . . . . . . . . . . . . . . . . . . . 7
62 4.3. accept-patch . . . . . . . . . . . . . . . . . . . . . . . 7
63 4.4. accept-post . . . . . . . . . . . . . . . . . . . . . . . 8
64 4.5. accept-ranges . . . . . . . . . . . . . . . . . . . . . . 8
65 4.6. accept-prefer . . . . . . . . . . . . . . . . . . . . . . 8
66 4.7. docs . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
67 4.8. precondition-req . . . . . . . . . . . . . . . . . . . . . 9
68 4.9. auth-req . . . . . . . . . . . . . . . . . . . . . . . . . 9
69 4.10. status . . . . . . . . . . . . . . . . . . . . . . . . . . 9
70 5. Representation Hints . . . . . . . . . . . . . . . . . . . . . 10
71 6. Creating and Serving Home Documents . . . . . . . . . . . . . 10
72 6.1. Managing Change in Home Documents . . . . . . . . . . . . 10
73 6.2. Evolving and Mixing APIs with Home Documents . . . . . . . 11
74 6.3. Documenting APIs that use Home Documents . . . . . . . . . 11
75 7. Consuming Home Documents . . . . . . . . . . . . . . . . . . . 11
76 8. Security Considerations . . . . . . . . . . . . . . . . . . . 12
77 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12
78 9.1. HTTP Resource Hint Registry . . . . . . . . . . . . . . . 12
79 9.2. HTTP Representation Hint Registry . . . . . . . . . . . . 12
80 9.3. Media Type Registration . . . . . . . . . . . . . . . . . 12
81 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13
82 10.1. Normative References . . . . . . . . . . . . . . . . . . . 13
83 10.2. Informative References . . . . . . . . . . . . . . . . . . 13
84 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 14
85 Appendix B. Frequently Asked Questions . . . . . . . . . . . . . 14
86 B.1. Why not Microformats? . . . . . . . . . . . . . . . . . . 14
87 B.2. Why doesn't the format allow references or inheritance? . 15
88 B.3. What about authentication? . . . . . . . . . . . . . . . . 15
89 B.4. What about "Faults" (i.e., errors)? . . . . . . . . . . . 15
90 B.5. How Do I find the schema for a format? . . . . . . . . . . 15
91 B.6. How do I express complex query arguments? . . . . . . . . 15
92 Appendix C. Open Issues . . . . . . . . . . . . . . . . . . . . . 16
93 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 16
95 1. Introduction
97 There is an emerging preference for non-browser Web applications
98 (colloquially, "HTTP APIs") to use a link-driven approach to their
99 interactions to assure loose coupling, thereby enabling extensibility
100 and API evolution.
102 This is based upon experience with previous APIs that specified
103 static URI paths (such as
104 "http://api.example.com/v1.0/widgets/abc123/properties"), which have
105 resulted in brittle, tight coupling between clients and servers.
107 Sometimes, these APIs are documented by a document format like [WADL]
108 that is used as a design-time description; i.e., the URIs and other
109 information they describe are "baked into" client implementations.
111 In contrast, a "follow your nose" API advertises the resources
112 available to clients using link relations [RFC5988] and the formats
113 they support using internet media types [RFC6838]. A client can then
114 decide - at run time - which resources to interact with based upon
115 its capabilities (as described by link relations), and the server can
116 safely add new resources and formats without disturbing clients that
117 are not yet aware of them.
119 As such, clients need to be able to discover this information quickly
120 and efficiently use it to interact with the server. Just as with a
121 human-targeted "home page" for a site, we can create a "home
122 document" for a HTTP API that describes it to non-browser clients.
124 Of course, an HTTP API might use any format to do so; however, there
125 are advantages to having a standard home document format. This
126 specification suggests one for consideration, using the JSON format
127 [RFC4627].
129 1.1. Notational Conventions
131 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
132 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
133 document are to be interpreted as described in [RFC2119].
135 2. JSON Home Documents
137 A JSON Home Document uses the format described in [RFC4627] and has
138 the media type "application/json-home".
140 Its content consists of a root object with a "resources" property,
141 whose member names are link relation types (as defined by [RFC5988]),
142 and values are Resource Objects, defined below.
144 For example:
146 GET / HTTP/1.1
147 Host: example.org
148 Accept: application/json-home
150 HTTP/1.1 200 OK
151 Content-Type: application/json-home
152 Cache-Control: max-age=3600
153 Connection: close
155 {
156 "resources": {
157 "http://example.org/rel/widgets": {
158 "href": "/widgets/"
159 },
160 "http://example.org/rel/widget": {
161 "href-template": "/widgets/{widget_id}",
162 "href-vars": {
163 "widget_id": "http://example.org/param/widget"
164 },
165 "hints": {
166 "allow": ["GET", "PUT", "DELETE", "PATCH"],
167 "formats": {
168 "application/json": {}
169 },
170 "accept-patch": ["application/json-patch"],
171 "accept-post": ["application/xml"],
172 "accept-ranges": ["bytes"]
173 }
174 }
175 }
176 }
178 Here, we have a home document that links to a resource, "/widgets/"
179 with the relation "http://example.org/rel/widgets". It also links to
180 an unknown number of resources with the relation type
181 "http://example.org/rel/widget" using a URI Template [RFC6570], along
182 with a mapping of identifiers to a variable for use in that template.
184 It also gives several hints about interacting with the latter
185 "widget" resources, including the HTTP methods usable with them, the
186 patch formats they accept, and the fact that they support partial
187 requests [I-D.ietf-httpbis-p5-range] using the "bytes" range-
188 specifier.
190 It gives no such hints about the "widgets" resource. This does not
191 mean that it (for example) doesn't support any HTTP methods; it means
192 that the client will need to discover this by interacting with the
193 resource, and/or examining the documentation for its link relation
194 type.
196 Effectively, this names a set of behaviors, as described by a
197 resource object, with a link relation type. This means that several
198 link relations might apply to a common base URL; e.g.:
200 {
201 "resources": {
202 "http://example.org/rel/search-by-id": {
203 "href-template": "/search?id={widget}",
204 "href-vars": {
205 "widget_name": "http://example.org/param/widget"
206 }
207 },
208 "http://example.org/rel/search-by-name": {
209 "href-template": "/search?name={widget_name}",
210 "href-vars": {
211 "widget_name": "http://example.org/param/widget_name"
212 }
213 }
214 }
215 }
217 3. Resource Objects
219 A Resource Object links to resources of the defined type using one of
220 two mechanisms; either a direct link (in which case there is exactly
221 one resource of that relation type associated with the API), or a
222 templated link, in which case there are zero to many such resources.
224 Direct links are indicated with an "href" property, whose value is a
225 URI [RFC3986].
227 Templated links are indicated with an "href-template" property, whose
228 value is a URI Template [RFC6570]. When "href-template" is present,
229 the Resource Object MUST have a "href-vars" property; see "Resolving
230 Templated Links".
232 Resource Objects MUST have exactly one of the "href" and "href-vars"
233 properties.
235 In both forms, the links that "href" and "href-template" refer to are
236 URI-references [RFC3986] whose base URI is that of the JSON Home
237 Document itself.
239 Resource Objects MAY also have a "hints" property, whose value is an
240 object that uses named Resource Hints (see Section 4) as its
241 properties.
243 3.1. Resolving Templated Links
245 A URI can be derived from a Templated Link by treating the "href-
246 template" value as a Level 3 URI Template [RFC6570], using the "href-
247 vars" property to fill the template.
249 The "href-vars" property, in turn, is an object that acts as a
250 mapping between variable names available to the template and absolute
251 URIs that are used as global identifiers for the semantics and syntax
252 of those variables.
254 For example, given the following Resource Object:
256 "http://example.org/rel/widget": {
257 "href-template": "/widgets/{widget_id}",
258 "href-vars": {
259 "widget_id": "http://example.org/param/widget"
260 },
261 "hints": {
262 "allow": ["GET", "PUT", "DELETE", "PATCH"],
263 "formats": {
264 "application/json": {}
265 },
266 "accept-patch": ["application/json-patch"],
267 "accept-post": ["application/xml"],
268 "accept-ranges": ["bytes"]
269 }
270 }
272 If you understand that "http://example.org/param/widget" is an
273 numeric identifier for a widget (perhaps by dereferencing that URL
274 and reading the documentation), you can then find the resource
275 corresponding to widget number 12345 at
276 "http://example.org/widgets/12345" (assuming that the Home Document
277 is located at "http://example.org/").
279 4. Resource Hints
281 Resource hints allow clients to find relevant information about
282 interacting with a resource beforehand, as a means of optimising
283 communications, as well as advertising available behaviours (e.g., to
284 aid in laying out a user interface for consuming the API).
286 Hints are just that - they are not a "contract", and are to only be
287 taken as advisory. The runtime behaviour of the resource always
288 overrides hinted information.
290 For example, a resource might hint that the PUT method is allowed on
291 all "widget" resources. This means that generally, the user has the
292 ability to PUT to a particular resource, but a specific resource
293 might reject a PUT based upon access control or other considerations.
294 More fine-grained information might be gathered by interacting with
295 the resource (e.g., via a GET), or by another resource "containing"
296 it (such as a "widgets" collection) or describing it (e.g., one
297 linked to it with a "describedby" link relation).
299 This specification defines a set of common hints, based upon
300 information that's discoverable by directly interacting with
301 resources. See Section 9.1 for information on defining new hints.
303 4.1. allow
305 o Resource Hint Name: allow
306 o Description: Hints the HTTP methods that the current client will
307 be able to use to interact with the resource; equivalent to the
308 Allow HTTP response header.
309 o Specification: [this document]
311 Content MUST be an array of strings, containing HTTP methods.
313 4.2. formats
315 o Resource Hint Name: formats
316 o Description: Hints the representation types that the resource
317 produces and consumes, using the GET and PUT methods respectively,
318 subject to the 'allow' hint.
319 o Specification: [this document]
321 Content MUST be an object, whose keys are media types, and values are
322 objects containing Representation Hints (see Section 5).
324 4.3. accept-patch
326 o Resource Hint Name: accept-patch
327 o Description: Hints the PATCH [RFC5789] request formats accepted by
328 the resource for this client; equivalent to the Accept-Patch HTTP
329 response header.
331 o Specification: [this document]
333 Content MUST be an array of strings, containing media types.
335 When this hint is present, "PATCH" SHOULD be listed in the "allow"
336 hint.
338 4.4. accept-post
340 o Resource Hint Name: accept-post
341 o Description: Hints the POST request formats accepted by the
342 resource for this client.
343 o Specification: [this document]
345 Content MUST be an array of strings, containing media types.
347 When this hint is present, "POST" SHOULD be listed in the "allow"
348 hint.
350 4.5. accept-ranges
352 o Resource Hint Name: accept-ranges
353 o Description: Hints the range-specifiers available to the client
354 for this resource; equivalent to the Accept-Ranges HTTP response
355 header [I-D.ietf-httpbis-p5-range].
356 o Specification: [this document]
358 Content MUST be an array of strings, containing HTTP range-
359 specifiers.
361 4.6. accept-prefer
363 o Resource Hint Name: accept-prefer
364 o Description: Hints the preferences [I-D.snell-http-prefer]
365 supported by the resource. Note that, as per that specifications,
366 a preference can be ignored by the server.
367 o Specification: [this document]
369 Content MUST be an array of strings, contain preferences.
371 4.7. docs
373 o Resource Hint Name: docs
374 o Description: Hints the location for human-readable documentation
375 for the relation type of the resource.
376 o Specification: [this document]
378 Content MUST be a string containing an absolute-URI [RFC3986]
379 referring to documentation that SHOULD be in HTML format.
381 4.8. precondition-req
383 o Resource Hint Name: precondition-req
384 o Description: Hints that the resource requires state-changing
385 requests (e.g., PUT, PATCH) to include a precondition, as per
386 [I-D.ietf-httpbis-p4-conditional], to avoid conflicts due to
387 concurrent updates.
388 o Specification: [this document]
390 Content MUST be an array of strings, with possible values "etag" and
391 "last-modified" indicating type of precondition expected.
393 4.9. auth-req
395 o Resource Hint Name: auth-req
396 o Description: Hints that the resource requires authentication using
397 the HTTP Authentication Framework [I-D.ietf-httpbis-p7-auth].
398 o Specification: [this document]
400 Content MUST be an array of objects, each with a "scheme" property
401 containing a string that corresponds to a HTTP authentication scheme,
402 and optionally a "realms" property containing an array of zero to
403 many strings that identify protection spaces that the resource is a
404 member of.
406 For example, a Resource Object might contain the following hint:
408 {
409 "auth-req": [
410 {
411 "scheme": "Basic",
412 "realms": ["private"]
413 }
414 ]
415 }
417 4.10. status
419 o Resource Hint Name: status
420 o Description: Hints the status of the resource.
421 o Specification: [this document]
423 Content MUST be a string; possible values are:
425 o "deprecated" - indicates that use of the resource is not
426 recommended, but it is still available.
427 o "gone" - indicates that the resource is no longer available; i.e.,
428 it will return a 410 Gone HTTP status code if accessed.
430 5. Representation Hints
432 TBD
434 6. Creating and Serving Home Documents
436 When making a home document available, there are a few things to keep
437 in mind:
439 o A home document is best located at a memorable URI, because its
440 URI will effectively become the URI for the API itself to clients.
441 o Home documents can be personalised, just as "normal" home pages
442 can. For example, you might advertise different URIs, and/or
443 different kinds of link relations, depending on the client's
444 identity.
445 o Home documents SHOULD be assigned a freshness lifetime (e.g.,
446 "Cache-Control: max-age=3600") so that clients can cache them, to
447 avoid having to fetch it every time the client interacts with the
448 service.
449 o Custom link relation types, as well as the URIs for variables,
450 should lead to documentation for those constructs.
452 6.1. Managing Change in Home Documents
454 The URIs used in home documents MAY change over time. However,
455 changing them can cause issues for clients that are relying on cached
456 home documents containing old links.
458 To mitigate the impact of such changes, servers SHOULD consider:
460 o Reducing the freshness lifetime of home documents before a link
461 change, so that clients are less likely to refer to an "old"
462 document.
463 o Regarding the "old" and "new" URIs as equally valid references for
464 an "overlap" period.
465 o After that period, handling requests for the "old" URIs
466 appropriately; e.g., with a 404 Not Found, or by redirecting the
467 client to the new URI.
469 6.2. Evolving and Mixing APIs with Home Documents
471 Using home documents affords the opportunity to change the "shape" of
472 the API over time, without breaking old clients.
474 This includes introducing new functions alongside the old ones - by
475 adding new link relation types with corresponding resource objects -
476 as well as adding new template variables, media types, and so on.
478 It's important to realise that a home document can serve more than
479 one "API" at a time; by listing all relevant relation types, it can
480 effectively "mix" different APIs, allowing clients to work with
481 different resources as they see fit.
483 6.3. Documenting APIs that use Home Documents
485 Another use case for "static" API description formats like WSDL and
486 WADL is to generate documentation for the API from them.
488 An API that uses the home document format correctly won't have a need
489 to do so, provided that the link relation types and media types it
490 uses are well-documented already.
492 7. Consuming Home Documents
494 Clients might use home documents in a variety of ways.
496 In the most common case - actually consuming the API - the client
497 will scan the Resources Object for the link relation(s) that it is
498 interested in, and then to interact with the resource(s) referred to.
499 Resource Hints can be used to optimise communication with the client,
500 as well as to inform as to the permissible actions (e.g., whether PUT
501 is likely to be supported).
503 Note that the home document is a "living" document; it does not
504 represent a "contract", but rather is expected to be inspected before
505 each interaction. In particular, links from the home document MUST
506 NOT be assumed to be valid beyond the freshness lifetime of the home
507 document, as per HTTP's caching model [I-D.ietf-httpbis-p6-cache].
509 As a result, clients SHOULD cache the home document (as per
510 [I-D.ietf-httpbis-p6-cache]), to avoid fetching it before every
511 interaction (which would otherwise be required).
513 Likewise, a client encountering a 404 Not Found on a link SHOULD
514 obtain a fresh copy of the home document, to assure that it is up-to-
515 date.
517 8. Security Considerations
519 Clients need to exercise care when using hints. For example, a naive
520 client might send credentials to a server that uses the auth-req
521 hint, without checking to see if those credentials are appropriate
522 for that server.
524 9. IANA Considerations
526 9.1. HTTP Resource Hint Registry
528 This specification defines the HTTP Resource Hint Registry. See
529 Section 4 for a general description of the function of resource
530 hints.
532 In particular, resource hints are generic; that is, they are
533 potentially applicable to any resource, not specific to one
534 application of HTTP, nor to one particular format. Generally, they
535 ought to be information that would otherwise be discoverable by
536 interacting with the resource.
538 Hint names MUST be composed of the lowercase letters (a-z), digits
539 (0-9), underscores ("_") and hyphens ("-"), and MUST begin with a
540 lowercase letter.
542 Hint content SHOULD be described in terms of JSON [RFC4627]
543 constructs.
545 New hints are registered using the Expert Review process described in
546 [RFC5226] to enforce the criteria above. Requests for registration
547 of new resource hints are to use the following template:
549 o Resource Hint Name: [hint name]
550 o Description: [a short description of the hint's semantics]
551 o Specification: [reference to specification document]
553 Initial registrations are enumerated in Section 4.
555 9.2. HTTP Representation Hint Registry
557 TBD
559 9.3. Media Type Registration
561 TBD
563 10. References
565 10.1. Normative References
567 [I-D.ietf-httpbis-p6-cache]
568 Fielding, R., Nottingham, M., and J. Reschke, "Hypertext
569 Transfer Protocol (HTTP/1.1): Caching",
570 draft-ietf-httpbis-p6-cache-22 (work in progress),
571 February 2013.
573 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
574 Requirement Levels", BCP 14, RFC 2119, March 1997.
576 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
577 Resource Identifier (URI): Generic Syntax", STD 66,
578 RFC 3986, January 2005.
580 [RFC4627] Crockford, D., "The application/json Media Type for
581 JavaScript Object Notation (JSON)", RFC 4627, July 2006.
583 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
584 IANA Considerations Section in RFCs", BCP 26, RFC 5226,
585 May 2008.
587 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010.
589 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
590 and D. Orchard, "URI Template", RFC 6570, March 2012.
592 10.2. Informative References
594 [I-D.ietf-httpbis-p4-conditional]
595 Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
596 (HTTP/1.1): Conditional Requests",
597 draft-ietf-httpbis-p4-conditional-22 (work in progress),
598 February 2013.
600 [I-D.ietf-httpbis-p5-range]
601 Fielding, R., Lafon, Y., and J. Reschke, "Hypertext
602 Transfer Protocol (HTTP/1.1): Range Requests",
603 draft-ietf-httpbis-p5-range-22 (work in progress),
604 February 2013.
606 [I-D.ietf-httpbis-p7-auth]
607 Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
608 (HTTP/1.1): Authentication", draft-ietf-httpbis-p7-auth-22
609 (work in progress), February 2013.
611 [I-D.snell-http-prefer]
612 Snell, J., "Prefer Header for HTTP",
613 draft-snell-http-prefer-18 (work in progress),
614 January 2013.
616 [MICROFORMATS]
617 microformats.org, "Microformats",
618 .
620 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP",
621 RFC 5789, March 2010.
623 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type
624 Specifications and Registration Procedures", BCP 13,
625 RFC 6838, January 2013.
627 [WADL] Hadley, M. and Sun Microsystems, "Web Application
628 Description Language",
629 .
631 [apps-discuss]
632 IETF, "IETF Apps-Discuss Mailing List",
633 .
635 Appendix A. Acknowledgements
637 Thanks to Jan Algermissen, Mike Amundsen, Bill Burke, Graham Klyne,
638 Leif Hedstrom, Jeni Tennison, Erik Wilde and Jorge Williams for their
639 suggestions and feedback.
641 Appendix B. Frequently Asked Questions
643 B.1. Why not Microformats?
645 Browser-centric Web applications use HTML as their representation
646 format of choice. While it is possible to augment HTML for non-
647 browser clients (using techniques like Microformats [MICROFORMATS]),
648 a few issues become evident when doing so:
650 o HTML has a very forgiving syntax. While this is appropriate for
651 browsers (especially considering that there are many million HTML
652 authors in the world), it makes for a less-than-precise language
653 for machines, resulting in both overhead (parsing and
654 transmission) as well as lack of precision.
656 o HTML is presentation-centric, making it tempting to reformat it
657 from time to time, to improve the "look and feel" of a page.
658 However, doing so can cause comparatively brittle non-browser
659 clients to lose their understanding of the content's semantics,
660 unless very careful controls are in place.
662 Because of this, it's most practical to define a separate format, and
663 JSON is easily machine-readable, precise, and has a better chance of
664 being managed for stability.
666 B.2. Why doesn't the format allow references or inheritance?
668 Adding inheritance or references would allow more modularity in the
669 format and make it more compact, at the cost of considerable
670 complexity and the associated potential for errors (both in the
671 specification and by its users).
673 Since good tools and compression are effective ways to achieve the
674 same ends, this specification doesn't attempt them.
676 B.3. What about authentication?
678 In HTTP, authentication is discoverable by interacting with the
679 resource (usually, by getting a 401 Unauthorized response status
680 code, along with one or more challenges). While the home document
681 could hint it, this isn't yet done, to avoid possible security
682 complications.
684 B.4. What about "Faults" (i.e., errors)?
686 In HTTP, errors are conveyed by HTTP status codes. While this
687 specification could (and even may) allow enumeration of possible
688 error conditions, there's a concern that this will encourage
689 applications to define many such "faults", leading to tight coupling
690 between the application and its clients.
692 B.5. How Do I find the schema for a format?
694 That isn't addressed by home documents. Ultimately, it's up to the
695 media type accepted and generated by resources to define and
696 constrain (or not) their syntax.
698 B.6. How do I express complex query arguments?
700 Complex queries - i.e., those that exceed the expressive power of
701 Link Templates or would require ambiguous properties of a "resources"
702 object - aren't intended to be defined by a home document. The
703 appropriate way to do this is with a "form" language, much as HTML
704 defines.
706 Note that it is possible to support multiple query syntaxes on the
707 same base URL, using more than one link relation type; see the
708 example at the start of the document.
710 Appendix C. Open Issues
712 The following is a list of placeholders for open issues.
714 o top-level object(s)
715 * contact details
716 * overall documentation
717 * release info?
718 * ToS
719 * rate limiting (per-resource?)
720 o Resource Hints
721 * indicate a POST to 201 Created pattern
722 * indicate an "action" POST
723 * outbound links
724 * forms?
725 o Representation Hints
726 * format profiles
727 * deprecation
728 o Defining new top-level and resource object properties - how new
729 ones are minted, registry, etc.
730 o Discovery (e.g., conneg, .well-known, etc.)
731 o LIMITED include function?
733 Author's Address
735 Mark Nottingham
737 Email: mnot@mnot.net
738 URI: http://www.mnot.net/