idnits 2.17.00 (12 Aug 2021) /tmp/idnits28249/draft-nottingham-json-home-04.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 23, 2016) is 2188 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) Summary: 3 errors (**), 0 flaws (~~), 1 warning (==), 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 23, 2016 4 Intended status: Informational 5 Expires: November 24, 2016 7 Home Documents for HTTP APIs 8 draft-nottingham-json-home-04 10 Abstract 12 This document proposes a "home document" format for non-browser HTTP 13 clients. 15 Note to Readers 17 The issues list for this draft can be found at 18 https://github.com/mnot/I-D/labels/json-home . 20 The most recent (often, unpublished) draft is at 21 https://mnot.github.io/I-D/json-home/ . 23 Recent changes are listed at https://github.com/mnot/I-D/commits/gh- 24 pages/json-home . 26 For information about implementations, see https://github.com/mnot/I- 27 D/wiki/json-home . 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at http://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on November 24, 2016. 46 Copyright Notice 48 Copyright (c) 2016 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (http://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 64 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4 65 2. JSON Home Documents . . . . . . . . . . . . . . . . . . . . . 4 66 3. Resource Objects . . . . . . . . . . . . . . . . . . . . . . 5 67 3.1. Resolving Templated Links . . . . . . . . . . . . . . . . 6 68 4. Resource Hints . . . . . . . . . . . . . . . . . . . . . . . 7 69 4.1. allow . . . . . . . . . . . . . . . . . . . . . . . . . . 8 70 4.2. formats . . . . . . . . . . . . . . . . . . . . . . . . . 8 71 4.3. accept-patch . . . . . . . . . . . . . . . . . . . . . . 8 72 4.4. accept-post . . . . . . . . . . . . . . . . . . . . . . . 8 73 4.5. accept-ranges . . . . . . . . . . . . . . . . . . . . . . 9 74 4.6. accept-prefer . . . . . . . . . . . . . . . . . . . . . . 9 75 4.7. docs . . . . . . . . . . . . . . . . . . . . . . . . . . 9 76 4.8. precondition-req . . . . . . . . . . . . . . . . . . . . 9 77 4.9. auth-req . . . . . . . . . . . . . . . . . . . . . . . . 10 78 4.10. status . . . . . . . . . . . . . . . . . . . . . . . . . 10 79 5. Representation Hints . . . . . . . . . . . . . . . . . . . . 11 80 6. Creating and Serving Home Documents . . . . . . . . . . . . . 11 81 6.1. Managing Change in Home Documents . . . . . . . . . . . . 11 82 6.2. Evolving and Mixing APIs with Home Documents . . . . . . 12 83 6.3. Documenting APIs that use Home Documents . . . . . . . . 12 84 7. Consuming Home Documents . . . . . . . . . . . . . . . . . . 12 85 8. Security Considerations . . . . . . . . . . . . . . . . . . . 13 86 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 87 9.1. HTTP Resource Hint Registry . . . . . . . . . . . . . . . 13 88 9.2. HTTP Representation Hint Registry . . . . . . . . . . . . 13 89 9.3. Media Type Registration . . . . . . . . . . . . . . . . . 14 90 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 91 10.1. Normative References . . . . . . . . . . . . . . . . . . 14 92 10.2. Informative References . . . . . . . . . . . . . . . . . 14 93 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 15 94 Appendix B. Frequently Asked Questions . . . . . . . . . . . . . 16 95 B.1. Why not Microformats? . . . . . . . . . . . . . . . . . . 16 96 B.2. Why doesn't the format allow references or inheritance? . 16 97 B.3. What about authentication? . . . . . . . . . . . . . . . 16 98 B.4. What about "Faults" (i.e., errors)? . . . . . . . . . . . 16 99 B.5. How Do I find the schema for a format? . . . . . . . . . 17 100 B.6. How do I express complex query arguments? . . . . . . . . 17 101 Appendix C. Open Issues . . . . . . . . . . . . . . . . . . . . 17 102 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 18 104 1. Introduction 106 There is an emerging preference for non-browser Web applications 107 (colloquially, "HTTP APIs") to use a link-driven approach to their 108 interactions to assure loose coupling, thereby enabling extensibility 109 and API evolution. 111 This is based upon experience with previous APIs that specified 112 static URI paths (such as 113 "http://api.example.com/v1.0/widgets/abc123/properties"), which have 114 resulted in brittle, tight coupling between clients and servers. 116 Sometimes, these APIs are documented by a document format like [WADL] 117 that is used as a design-time description; i.e., the URIs and other 118 information they describe are "baked into" client implementations. 120 In contrast, a "follow your nose" API advertises the resources 121 available to clients using link relations [RFC5988] and the formats 122 they support using internet media types [RFC6838]. A client can then 123 decide - at run time - which resources to interact with based upon 124 its capabilities (as described by link relations), and the server can 125 safely add new resources and formats without disturbing clients that 126 are not yet aware of them. 128 As such, clients need to be able to discover this information quickly 129 and efficiently use it to interact with the server. Just as with a 130 human-targeted "home page" for a site, we can create a "home 131 document" for a HTTP API that describes it to non-browser clients. 133 Of course, an HTTP API might use any format to do so; however, there 134 are advantages to having a standard home document format. This 135 specification suggests one for consideration, using t he JSON format 136 [RFC7159]. 138 1.1. Notational Conventions 140 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 141 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 142 document are to be interpreted as described in [RFC2119]. 144 2. JSON Home Documents 146 A JSON Home Document uses the format described in [RFC7159] and has 147 the media type "application/json-home". 149 Its content consists of a root object with a "resources" property, 150 whose member names are link relation types (as defined by [RFC5988]), 151 and values are Resource Objects, defined below. 153 For example: 155 GET / HTTP/1.1 156 Host: example.org 157 Accept: application/json-home 159 HTTP/1.1 200 OK 160 Content-Type: application/json-home 161 Cache-Control: max-age=3600 162 Connection: close 164 { 165 "resources": { 166 "tag:me@example.com,2016:widgets": { 167 "href": "/widgets/" 168 }, 169 "tag:me@example.com,2016:widget": { 170 "href-template": "/widgets/{widget_id}", 171 "href-vars": { 172 "widget_id": "http://example.org/param/widget" 173 }, 174 "hints": { 175 "allow": ["GET", "PUT", "DELETE", "PATCH"], 176 "formats": { 177 "application/json": {} 178 }, 179 "accept-patch": ["application/json-patch+json"], 180 "accept-post": ["application/xml"], 181 "accept-ranges": ["bytes"] 182 } 183 } 184 } 185 } 187 Here, we have a home document that links to a resource, "/widgets/" 188 with the relation "tag:me@example.com,2016:widgets". It also links 189 to an unknown number of resources with the relation type 190 "tag:me@example.com,2016:widget" using a URI Template [RFC6570], 191 along with a mapping of identifiers to a variable for use in that 192 template. 194 It also gives several hints about interacting with the latter 195 "widget" resources, including the HTTP methods usable with them, the 196 patch formats they accept, and the fact that they support partial 197 requests [RFC7233] using the "bytes" range-specifier. 199 It gives no such hints about the "widgets" resource. This does not 200 mean that it (for example) doesn't support any HTTP methods; it means 201 that the client will need to discover this by interacting with the 202 resource, and/or examining the documentation for its link relation 203 type. 205 Effectively, this names a set of behaviors, as described by a 206 resource object, with a link relation type. This means that several 207 link relations might apply to a common base URL; e.g.: 209 { 210 "resources": { 211 "tag:me@example.com,2016:search-by-id": { 212 "href-template": "/search?id={widget_id}", 213 "href-vars": { 214 "widget_id": "http://example.org/param/widget_id" 215 } 216 }, 217 "tag:me@example.com,2016:search-by-name": { 218 "href-template": "/search?name={widget_name}", 219 "href-vars": { 220 "widget_name": "http://example.org/param/widget_name" 221 } 222 } 223 } 224 } 226 Note that the examples above use both tag [RFC4151] and http 227 [RFC7230] URIs; any URI scheme can be used to identify link relations 228 and other artefacts in home documents. 230 3. Resource Objects 232 A Resource Object links to resources of the defined type using one of 233 two mechanisms; either a direct link (in which case there is exactly 234 one resource of that relation type associated with the API), or a 235 templated link, in which case there are zero to many such resources. 237 Direct links are indicated with an "href" property, whose value is a 238 URI [RFC3986]. 240 Templated links are indicated with an "href-template" property, whose 241 value is a URI Template [RFC6570]. When "href-template" is present, 242 the Resource Object MUST have a "href-vars" property; see "Resolving 243 Templated Links". 245 Resource Objects MUST have exactly one of the "href" and "href-vars" 246 properties. 248 In both forms, the links that "href" and "href-template" refer to are 249 URI-references [RFC3986] whose base URI is that of the JSON Home 250 Document itself. 252 Resource Objects MAY also have a "hints" property, whose value is an 253 object that uses named Resource Hints (see Section 4) as its 254 properties. 256 3.1. Resolving Templated Links 258 A URI can be derived from a Templated Link by treating the "href- 259 template" value as a Level 3 URI Template [RFC6570], using the "href- 260 vars" property to fill the template. 262 The "href-vars" property, in turn, is an object that acts as a 263 mapping between variable names available to the template and absolute 264 URIs that are used as global identifiers for the semantics and syntax 265 of those variables. 267 For example, given the following Resource Object: 269 "http://example.org/rel/widget": { 270 "href-template": "/widgets/{widget_id}", 271 "href-vars": { 272 "widget_id": "http://example.org/param/widget" 273 }, 274 "hints": { 275 "allow": ["GET", "PUT", "DELETE", "PATCH"], 276 "formats": { 277 "application/json": {} 278 }, 279 "accept-patch": ["application/json-patch+json"], 280 "accept-post": ["application/xml"], 281 "accept-ranges": ["bytes"] 282 } 283 } 285 If you understand that "http://example.org/param/widget" is an 286 numeric identifier for a widget, you can then find the resource 287 corresponding to widget number 12345 at "http://example.org/ 288 widgets/12345" (assuming that the Home Document is located at 289 "http://example.org/"). 291 4. Resource Hints 293 Resource hints allow clients to find relevant information about 294 interacting with a resource beforehand, as a means of optimizing 295 communications, as well as advertising available behaviors (e.g., to 296 aid in laying out a user interface for consuming the API). 298 Hints are just that - they are not a "contract", and are to only be 299 taken as advisory. The runtime behavior of the resource always 300 overrides hinted information. 302 For example, a resource might hint that the PUT method is allowed on 303 all "widget" resources. This means that generally, the user has the 304 ability to PUT to a particular resource, but a specific resource 305 might reject a PUT based upon access control or other considerations. 306 More fine-grained information might be gathered by interacting with 307 the resource (e.g., via a GET), or by another resource "containing" 308 it (such as a "widgets" collection) or describing it (e.g., one 309 linked to it with a "describedby" link relation). 311 This specification defines a set of common hints, based upon 312 information that's discoverable by directly interacting with 313 resources. See Section 9.1 for information on defining new hints. 315 4.1. allow 317 o Resource Hint Name: allow 319 o Description: Hints the HTTP methods that the current client will 320 be able to use to interact with the resource; equivalent to the 321 Allow HTTP response header. 323 o Specification: [this document] 325 Content MUST be an array of strings, containing HTTP methods. 327 4.2. formats 329 o Resource Hint Name: formats 331 o Description: Hints the representation types that the resource 332 produces and consumes, using the GET and PUT methods respectively, 333 subject to the 'allow' hint. 335 o Specification: [this document] 337 Content MUST be an object, whose keys are media types, and values are 338 objects containing Representation Hints (see Section 5). 340 4.3. accept-patch 342 o Resource Hint Name: accept-patch 344 o Description: Hints the PATCH [RFC5789] request formats accepted by 345 the resource for this client; equivalent to the Accept-Patch HTTP 346 response header. 348 o Specification: [this document] 350 Content MUST be an array of strings, containing media types. 352 When this hint is present, "PATCH" SHOULD be listed in the "allow" 353 hint. 355 4.4. accept-post 357 o Resource Hint Name: accept-post 359 o Description: Hints the POST request formats accepted by the 360 resource for this client. 362 o Specification: [this document] 363 Content MUST be an array of strings, containing media types. 365 When this hint is present, "POST" SHOULD be listed in the "allow" 366 hint. 368 4.5. accept-ranges 370 o Resource Hint Name: accept-ranges 372 o Description: Hints the range-specifiers available to the client 373 for this resource; equivalent to the Accept-Ranges HTTP response 374 header [RFC7233]. 376 o Specification: [this document] 378 Content MUST be an array of strings, containing HTTP range- 379 specifiers. 381 4.6. accept-prefer 383 o Resource Hint Name: accept-prefer 385 o Description: Hints the preferences [RFC7240] supported by the 386 resource. Note that, as per that specifications, a preference can 387 be ignored by the server. 389 o Specification: [this document] 391 Content MUST be an array of strings, contain preferences. 393 4.7. docs 395 o Resource Hint Name: docs 397 o Description: Hints the location for human-readable documentation 398 for the relation type of the resource. 400 o Specification: [this document] 402 Content MUST be a string containing an absolute-URI [RFC3986] 403 referring to documentation that SHOULD be in HTML format. 405 4.8. precondition-req 407 o Resource Hint Name: precondition-req 408 o Description: Hints that the resource requires state-changing 409 requests (e.g., PUT, PATCH) to include a precondition, as per 410 [RFC7232], to avoid conflicts due to concurrent updates. 412 o Specification: [this document] 414 Content MUST be an array of strings, with possible values "etag" and 415 "last-modified" indicating type of precondition expected. 417 4.9. auth-req 419 o Resource Hint Name: auth-req 421 o Description: Hints that the resource requires authentication using 422 the HTTP Authentication Framework [RFC7235]. 424 o Specification: [this document] 426 Content MUST be an array of objects, each with a "scheme" property 427 containing a string that corresponds to a HTTP authentication scheme, 428 and optionally a "realms" property containing an array of zero to 429 many strings that identify protection spaces that the resource is a 430 member of. 432 For example, a Resource Object might contain the following hint: 434 { 435 "auth-req": [ 436 { 437 "scheme": "Basic", 438 "realms": ["private"] 439 } 440 ] 441 } 443 4.10. status 445 o Resource Hint Name: status 447 o Description: Hints the status of the resource. 449 o Specification: [this document] 451 Content MUST be a string; possible values are: 453 o "deprecated" - indicates that use of the resource is not 454 recommended, but it is still available. 456 o "gone" - indicates that the resource is no longer available; i.e., 457 it will return a 410 Gone HTTP status code if accessed. 459 5. Representation Hints 461 TBD 463 6. Creating and Serving Home Documents 465 When making a home document available, there are a few things to keep 466 in mind: 468 o A home document is best located at a memorable URI, because its 469 URI will effectively become the URI for the API itself to clients. 471 o Home documents can be personalized, just as "normal" home pages 472 can. For example, you might advertise different URIs, and/or 473 different kinds of link relations, depending on the client's 474 identity. 476 o Home documents SHOULD be assigned a freshness lifetime (e.g., 477 "Cache-Control: max-age=3600") so that clients can cache them, to 478 avoid having to fetch it every time the client interacts with the 479 service. 481 o Custom link relation types, as well as the URIs for variables, 482 should lead to documentation for those constructs. 484 6.1. Managing Change in Home Documents 486 The URIs used in home documents MAY change over time. However, 487 changing them can cause issues for clients that are relying on cached 488 home documents containing old links. 490 To mitigate the impact of such changes, servers SHOULD consider: 492 o Reducing the freshness lifetime of home documents before a link 493 change, so that clients are less likely to refer to an "old" 494 document. 496 o Regarding the "old" and "new" URIs as equally valid references for 497 an "overlap" period. 499 o After that period, handling requests for the "old" URIs 500 appropriately; e.g., with a 404 Not Found, or by redirecting the 501 client to the new URI. 503 6.2. Evolving and Mixing APIs with Home Documents 505 Using home documents affords the opportunity to change the "shape" of 506 the API over time, without breaking old clients. 508 This includes introducing new functions alongside the old ones - by 509 adding new link relation types with corresponding resource objects - 510 as well as adding new template variables, media types, and so on. 512 It's important to realise that a home document can serve more than 513 one "API" at a time; by listing all relevant relation types, it can 514 effectively "mix" different APIs, allowing clients to work with 515 different resources as they see fit. 517 6.3. Documenting APIs that use Home Documents 519 Another use case for "static" API description formats like WSDL and 520 WADL is to generate documentation for the API from them. 522 An API that uses the home document format correctly won't have a need 523 to do so, provided that the link relation types and media types it 524 uses are well-documented already. 526 7. Consuming Home Documents 528 Clients might use home documents in a variety of ways. 530 In the most common case - actually consuming the API - the client 531 will scan the Resources Object for the link relation(s) that it is 532 interested in, and then to interact with the resource(s) referred to. 533 Resource Hints can be used to optimize communication with the client, 534 as well as to inform as to the permissible actions (e.g., whether PUT 535 is likely to be supported). 537 Note that the home document is a "living" document; it does not 538 represent a "contract", but rather is expected to be inspected before 539 each interaction. In particular, links from the home document MUST 540 NOT be assumed to be valid beyond the freshness lifetime of the home 541 document, as per HTTP's caching model [RFC7234]. 543 As a result, clients SHOULD cache the home document (as per 544 [RFC7234]), to avoid fetching it before every interaction (which 545 would otherwise be required). 547 Likewise, a client encountering a 404 Not Found on a link SHOULD 548 obtain a fresh copy of the home document, to assure that it is up-to- 549 date. 551 8. Security Considerations 553 Clients need to exercise care when using hints. For example, a naive 554 client might send credentials to a server that uses the auth-req 555 hint, without checking to see if those credentials are appropriate 556 for that server. 558 9. IANA Considerations 560 9.1. HTTP Resource Hint Registry 562 This specification defines the HTTP Resource Hint Registry. See 563 Section 4 for a general description of the function of resource 564 hints. 566 In particular, resource hints are generic; that is, they are 567 potentially applicable to any resource, not specific to one 568 application of HTTP, nor to one particular format. Generally, they 569 ought to be information that would otherwise be discoverable by 570 interacting with the resource. 572 Hint names MUST be composed of the lowercase letters (a-z), digits 573 (0-9), underscores ("_") and hyphens ("-"), and MUST begin with a 574 lowercase letter. 576 Hint content SHOULD be described in terms of JSON [RFC7159] 577 constructs. 579 New hints are registered using the Expert Review process described in 580 [RFC5226] to enforce the criteria above. Requests for registration 581 of new resource hints are to use the following template: 583 o Resource Hint Name: [hint name] 585 o Description: [a short description of the hint's semantics] 587 o Specification: [reference to specification document] 589 Initial registrations are enumerated in Section 4. 591 9.2. HTTP Representation Hint Registry 593 TBD 595 9.3. Media Type Registration 597 TBD 599 10. References 601 10.1. Normative References 603 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 604 Requirement Levels", BCP 14, RFC 2119, 605 DOI 10.17487/RFC2119, March 1997, 606 . 608 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 609 Resource Identifier (URI): Generic Syntax", STD 66, 610 RFC 3986, DOI 10.17487/RFC3986, January 2005, 611 . 613 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 614 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 615 DOI 10.17487/RFC5226, May 2008, 616 . 618 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 619 DOI 10.17487/RFC5988, October 2010, 620 . 622 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 623 and D. Orchard, "URI Template", RFC 6570, 624 DOI 10.17487/RFC6570, March 2012, 625 . 627 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 628 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 629 2014, . 631 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 632 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 633 RFC 7234, DOI 10.17487/RFC7234, June 2014, 634 . 636 10.2. Informative References 638 [MICROFORMATS] 639 microformats.org, "Microformats", n.d., 640 . 642 [RFC4151] Kindberg, T. and S. Hawke, "The 'tag' URI Scheme", 643 RFC 4151, DOI 10.17487/RFC4151, October 2005, 644 . 646 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 647 RFC 5789, DOI 10.17487/RFC5789, March 2010, 648 . 650 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 651 Specifications and Registration Procedures", BCP 13, 652 RFC 6838, DOI 10.17487/RFC6838, January 2013, 653 . 655 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 656 Protocol (HTTP/1.1): Message Syntax and Routing", 657 RFC 7230, DOI 10.17487/RFC7230, June 2014, 658 . 660 [RFC7232] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 661 Protocol (HTTP/1.1): Conditional Requests", RFC 7232, 662 DOI 10.17487/RFC7232, June 2014, 663 . 665 [RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., 666 "Hypertext Transfer Protocol (HTTP/1.1): Range Requests", 667 RFC 7233, DOI 10.17487/RFC7233, June 2014, 668 . 670 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 671 Protocol (HTTP/1.1): Authentication", RFC 7235, 672 DOI 10.17487/RFC7235, June 2014, 673 . 675 [RFC7240] Snell, J., "Prefer Header for HTTP", RFC 7240, 676 DOI 10.17487/RFC7240, June 2014, 677 . 679 [WADL] Hadley, M. and Sun Microsystems, "Web Application 680 Description Language", n.d., 681 . 683 Appendix A. Acknowledgements 685 Thanks to Jan Algermissen, Mike Amundsen, Bill Burke, Sven Dietze, 686 Graham Klyne, Leif Hedstrom, Joe Hildebrand, Jeni Tennison, Erik 687 Wilde and Jorge Williams for their suggestions and feedback. 689 Appendix B. Frequently Asked Questions 691 B.1. Why not Microformats? 693 Browser-centric Web applications use HTML as their representation 694 format of choice. While it is possible to augment HTML for non- 695 browser clients (using techniques like Microformats [MICROFORMATS]), 696 a few issues become evident when doing so: 698 o HTML has a very forgiving syntax. While this is appropriate for 699 browsers (especially considering that there are many million HTML 700 authors in the world), it makes for a less-than-precise language 701 for machines, resulting in both overhead (parsing and 702 transmission) as well as lack of precision. 704 o HTML is presentation-centric, making it tempting to reformat it 705 from time to time, to improve the "look and feel" of a page. 706 However, doing so can cause comparatively brittle non-browser 707 clients to lose their understanding of the content's semantics, 708 unless very careful controls are in place. 710 Because of this, it's most practical to define a separate format, and 711 JSON is easily machine-readable, precise, and has a better chance of 712 being managed for stability. 714 B.2. Why doesn't the format allow references or inheritance? 716 Adding inheritance or references would allow more modularity in the 717 format and make it more compact, at the cost of considerable 718 complexity and the associated potential for errors (both in the 719 specification and by its users). 721 Since good tools and compression are effective ways to achieve the 722 same ends, this specification doesn't attempt them. 724 B.3. What about authentication? 726 In HTTP, authentication is discoverable by interacting with the 727 resource (usually, by getting a 401 Unauthorized response status 728 code, along with one or more challenges). While the home document 729 could hint it, this isn't yet done, to avoid possible security 730 complications. 732 B.4. What about "Faults" (i.e., errors)? 734 In HTTP, errors are conveyed by HTTP status codes. While this 735 specification could (and even may) allow enumeration of possible 736 error conditions, there's a concern that this will encourage 737 applications to define many such "faults", leading to tight coupling 738 between the application and its clients. 740 B.5. How Do I find the schema for a format? 742 That isn't addressed by home documents. Ultimately, it's up to the 743 media type accepted and generated by resources to define and 744 constrain (or not) their syntax. 746 B.6. How do I express complex query arguments? 748 Complex queries - i.e., those that exceed the expressive power of 749 Link Templates or would require ambiguous properties of a "resources" 750 object - aren't intended to be defined by a home document. The 751 appropriate way to do this is with a "form" language, much as HTML 752 defines. 754 Note that it is possible to support multiple query syntaxes on the 755 same base URL, using more than one link relation type; see the 756 example at the start of the document. 758 Appendix C. Open Issues 760 The following is a list of placeholders for open issues. 762 o top-level object(s) 764 * contact details 766 * overall documentation 768 * release info? 770 * ToS 772 * rate limiting (per-resource?) 774 o Resource Hints 776 * indicate a POST to 201 Created pattern 778 * indicate an "action" POST 780 * outbound links 782 * forms? 784 o Representation Hints 785 * format profiles 787 * deprecation 789 o Defining new top-level and resource object properties - how new 790 ones are minted, registry, etc. 792 o Discovery (e.g., conneg, .well-known, etc.) 794 o LIMITED include function? 796 Author's Address 798 Mark Nottingham 800 Email: mnot@mnot.net 801 URI: http://www.mnot.net/