idnits 2.17.1 draft-nottingham-json-home-05.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 (November 24, 2016) is 2703 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) ** Obsolete normative reference: RFC 7234 (Obsoleted by RFC 9111) -- Obsolete informational reference (is this intentional?): RFC 7230 (Obsoleted by RFC 9110, RFC 9112) -- Obsolete informational reference (is this intentional?): RFC 7232 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7233 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7235 (Obsoleted by RFC 9110) Summary: 4 errors (**), 0 flaws (~~), 1 warning (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Nottingham 3 Internet-Draft November 24, 2016 4 Intended status: Informational 5 Expires: May 28, 2017 7 Home Documents for HTTP APIs 8 draft-nottingham-json-home-05 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 May 28, 2017. 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. API Home Documents . . . . . . . . . . . . . . . . . . . . . 4 66 3. API Objects . . . . . . . . . . . . . . . . . . . . . . . . . 6 67 4. Resource Objects . . . . . . . . . . . . . . . . . . . . . . 7 68 4.1. Resolving Templated Links . . . . . . . . . . . . . . . . 7 69 5. Resource Hints . . . . . . . . . . . . . . . . . . . . . . . 8 70 5.1. allow . . . . . . . . . . . . . . . . . . . . . . . . . . 9 71 5.2. formats . . . . . . . . . . . . . . . . . . . . . . . . . 9 72 5.3. acceptPatch . . . . . . . . . . . . . . . . . . . . . . . 9 73 5.4. acceptPost . . . . . . . . . . . . . . . . . . . . . . . 9 74 5.5. acceptRanges . . . . . . . . . . . . . . . . . . . . . . 10 75 5.6. acceptPrefer . . . . . . . . . . . . . . . . . . . . . . 10 76 5.7. docs . . . . . . . . . . . . . . . . . . . . . . . . . . 10 77 5.8. preconditionRequired . . . . . . . . . . . . . . . . . . 10 78 5.9. authSchemes . . . . . . . . . . . . . . . . . . . . . . . 11 79 5.10. status . . . . . . . . . . . . . . . . . . . . . . . . . 11 80 6. Security Considerations . . . . . . . . . . . . . . . . . . . 12 81 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 82 7.1. HTTP Resource Hint Registry . . . . . . . . . . . . . . . 12 83 7.2. Media Type Registration . . . . . . . . . . . . . . . . . 13 84 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 85 8.1. Normative References . . . . . . . . . . . . . . . . . . 13 86 8.2. Informative References . . . . . . . . . . . . . . . . . 13 87 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 14 88 Appendix B. Considerations for Creating and Serving Home 89 Documents . . . . . . . . . . . . . . . . . . . . . 14 90 B.1. Managing Change in Home Documents . . . . . . . . . . . . 15 91 B.2. Evolving and Mixing APIs with Home Documents . . . . . . 15 92 Appendix C. Considerations for Consuming Home Documents . . . . 16 93 Appendix D. Frequently Asked Questions . . . . . . . . . . . . . 16 94 D.1. Why doesn't the format allow references or inheritance? . 16 95 D.2. What about "Faults" (i.e., errors)? . . . . . . . . . . . 16 96 D.3. How Do I find the schema for a format? . . . . . . . . . 17 97 D.4. How do I express complex query arguments? . . . . . . . . 17 98 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 17 100 1. Introduction 102 It is becoming increasingly common to use HTTP [RFC7230] for 103 applications other than traditional Web browsing. Such "HTTP APIs" 104 are used to integrate processes on disparate systems, make 105 information available to machines across the Internet, and as part of 106 the implementation of "micro-services." 108 By using HTTP, these applications realise a number of benefits, from 109 message framing to caching, and well-defined semantics that are 110 broadly understood and useful. 112 However, one of the core architectural tenants of the Web is the use 113 of links [RFC3986] to navigate between states; typically, these 114 applications document static URLs that clients need to know and 115 servers need to implement, and any interaction outside of these 116 bounds is uncharted territory. 118 In contrast, a link-driven application discovers relevant resources 119 at run time, using a shared vocabulary of link relations [RFC5988] 120 and internet media types [RFC6838] to support a "follow your nose" 121 style of interaction. 123 A client can then decide which resources to interact with "on the 124 fly" based upon its capabilities (as described by link relations), 125 and the server can safely add new resources and formats without 126 disturbing clients that are not yet aware of them. 128 Doing so can provide any of a number of benefits, including: 130 o Extensibility - Because new server capabilities can be expressed 131 as link relations, new features can be layered in without 132 introducing a new API version; clients will discover them in the 133 home document. This promotes loose coupling between clients and 134 servers. 136 o Evolvability - Likewise, interfaces can change gradually by 137 introducing a new link relation and/or format while still 138 supporting the old ones. 140 o Customisation - Home documents can be tailored for the client, 141 allowing diffrent classes of service or different client 142 permissions to be exposed naturally. 144 o Flexible deployment - Since URLs aren't baked into documentation, 145 the server can choose what URLs to use for a given service. 147 o API mixing - Likewise, more than one API can be deployed on a 148 given server, without fear of collisions. 150 Whether an application ought to use links in this fashion depends on 151 how it is deployed; generally, the most benefit will be received when 152 multiple instances of the service are deployed, possibly with 153 different versions, and they are consumed by clients with different 154 capabilities. In particular, Internet Standards that use HTTP as a 155 substrate are likely to require the attributes described above. 157 Clients need to be able to discover information about these 158 applications to use it efficiently; just as with a human-targeted 159 "home page" for a site, there is a need for a "home document" for a 160 HTTP API that describes it to non-browser clients. 162 Of course, an HTTP API might use any format to do so; however, there 163 are advantages to having a common home document format. This 164 specification defines one, using the JSON format [RFC7159]. 166 1.1. Notational Conventions 168 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 169 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 170 document are to be interpreted as described in [RFC2119]. 172 2. API Home Documents 174 An API Home Document (or, interchangeably, "home document") uses the 175 format described in [RFC7159] and has the media type "application/ 176 json-home". 178 Its content consists of a root object with: 180 o A "resources" member, whose value is an object that describes the 181 resources associated with the API. Its member names are link 182 relation types (as defined by [RFC5988]), and their values are 183 Resource Objects (Section 4). 185 o Optionally, a "api" member, whose value is an API Object 186 (Section 3) that contains information about the API as a whole. 188 For example: 190 GET / HTTP/1.1 191 Host: example.org 192 Accept: application/json-home 194 HTTP/1.1 200 OK 195 Content-Type: application/json-home 196 Cache-Control: max-age=3600 197 Connection: close 199 { 200 "api": { 201 "title": "Example API", 202 "links": { 203 "author": "mailto:api-admin@example.com", 204 "describedBy": "https://example.com/api-docs/" 205 } 206 } 207 "resources": { 208 "tag:me@example.com,2016:widgets": { 209 "href": "/widgets/" 210 }, 211 "tag:me@example.com,2016:widget": { 212 "hrefTemplate": "/widgets/{widget_id}", 213 "hrefVars": { 214 "widget_id": "https://example.org/param/widget" 215 }, 216 "hints": { 217 "allow": ["GET", "PUT", "DELETE", "PATCH"], 218 "formats": { 219 "application/json": {} 220 }, 221 "acceptPatch": ["application/json-patch+json"], 222 "acceptRanges": ["bytes"] 223 } 224 } 225 } 226 } 228 Here, we have a home document for the API "Example API", whose author 229 can be contacted at the e-mail address "api-admin@example.com", and 230 whose documentation is at "https://example.com/api-docs/". 232 It links to a resource "/widgets/" with the relation 233 "tag:me@example.com,2016:widgets". It also links to an unknown 234 number of resources with the relation type 235 "tag:me@example.com,2016:widget" using a URI Template [RFC6570], 236 along with a mapping of identifiers to a variable for use in that 237 template. 239 It also gives several hints about interacting with the latter 240 "widget" resources, including the HTTP methods usable with them, the 241 PATCH and POST formats they accept, and the fact that they support 242 partial requests [RFC7233] using the "bytes" range-specifier. 244 It gives no such hints about the "widgets" resource. This does not 245 mean that it (for example) doesn't support any HTTP methods; it means 246 that the client will need to discover this by interacting with the 247 resource, and/or examining the documentation for its link relation 248 type. 250 Effectively, this names a set of behaviors, as described by a 251 resource object, with a link relation type. This means that several 252 link relations might apply to a common base URL; e.g.: 254 { 255 "resources": { 256 "tag:me@example.com,2016:search-by-id": { 257 "hrefTemplate": "/search?id={widget_id}", 258 "hrefVars": { 259 "widget_id": "https://example.org/param/widget_id" 260 } 261 }, 262 "tag:me@example.com,2016:search-by-name": { 263 "hrefTemplate": "/search?name={widget_name}", 264 "hrefVars": { 265 "widget_name": "https://example.org/param/widget_name" 266 } 267 } 268 } 269 } 271 Note that the examples above use both tag [RFC4151] and https 272 [RFC7230] URIs; any URI scheme can be used to identify link relations 273 and other artefacts in home documents. 275 3. API Objects 277 An API Object contains links to information about the API itself. 279 Two members are defined: 281 o "title" has a string value indicating the name of the API; 282 o "links" has an object value, whose member names are link relation 283 types [RFC5988], and values are URLs [RFC3986]. The context of 284 these links is the API home document as a whole. 286 Future members MAY be defined by specifications that update this 287 document. 289 4. Resource Objects 291 A Resource Object links to resources of the defined type using one of 292 two mechanisms; either a direct link (in which case there is exactly 293 one resource of that relation type associated with the API), or a 294 templated link, in which case there are zero to many such resources. 296 Direct links are indicated with an "href" property, whose value is a 297 URI [RFC3986]. 299 Templated links are indicated with an "hrefTemplate" property, whose 300 value is a URI Template [RFC6570]. When "hrefTemplate" is present, 301 the Resource Object MUST have a "hrefVars" property; see "Resolving 302 Templated Links". 304 Resource Objects MUST have exactly one of the "href" and "href-vars" 305 properties. 307 In both forms, the links that "href" and "hrefTemplate" refer to are 308 URI-references [RFC3986] whose base URI is that of the API Home 309 Document itself. 311 Resource Objects MAY also have a "hints" property, whose value is an 312 object that uses named Resource Hints (see Section 5) as its 313 properties. 315 4.1. Resolving Templated Links 317 A URI can be derived from a Templated Link by treating the 318 "hrefTemplate" value as a Level 3 URI Template [RFC6570], using the 319 "hrefVars" property to fill the template. 321 The "hrefVars" property, in turn, is an object that acts as a mapping 322 between variable names available to the template and absolute URIs 323 that are used as global identifiers for the semantics and syntax of 324 those variables. 326 For example, given the following Resource Object: 328 "https://example.org/rel/widget": { 329 "hrefTemplate": "/widgets/{widget_id}", 330 "hrefVars": { 331 "widget_id": "https://example.org/param/widget" 332 }, 333 "hints": { 334 "allow": ["GET", "PUT", "DELETE", "PATCH"], 335 "formats": { 336 "application/json": {} 337 }, 338 "acceptPatch": ["application/json-patch+json"], 339 "acceptRanges": ["bytes"] 340 } 341 } 343 If you understand that "https://example.org/param/widget" is an 344 numeric identifier for a widget, you can then find the resource 345 corresponding to widget number 12345 at "https://example.org/ 346 widgets/12345" (assuming that the Home Document is located at 347 "https://example.org/"). 349 5. Resource Hints 351 Resource hints allow clients to find relevant information about 352 interacting with a resource beforehand, as a means of optimizing 353 communications, as well as advertising available behaviors (e.g., to 354 aid in laying out a user interface for consuming the API). 356 Hints are just that - they are not a "contract", and are to only be 357 taken as advisory. The runtime behavior of the resource always 358 overrides hinted information. 360 For example, a resource might hint that the PUT method is allowed on 361 all "widget" resources. This means that generally, the user has the 362 ability to PUT to a particular resource, but a specific resource 363 might reject a PUT based upon access control or other considerations. 364 More fine-grained information might be gathered by interacting with 365 the resource (e.g., via a GET), or by another resource "containing" 366 it (such as a "widgets" collection) or describing it (e.g., one 367 linked to it with a "describedBy" link relation). 369 This specification defines a set of common hints, based upon 370 information that's discoverable by directly interacting with 371 resources. See Section 7.1 for information on defining new hints. 373 5.1. allow 375 o Resource Hint Name: allow 377 o Description: Hints the HTTP methods that the current client will 378 be able to use to interact with the resource; equivalent to the 379 Allow HTTP response header. 381 o Specification: [this document] 383 Content MUST be an array of strings, containing HTTP methods. 385 5.2. formats 387 o Resource Hint Name: formats 389 o Description: Hints the representation types that the resource 390 produces and consumes, using the GET and PUT methods respectively, 391 subject to the 'allow' hint. 393 o Specification: [this document] 395 Content MUST be an object, whose keys are media types, and values are 396 objects, currently empty. 398 5.3. acceptPatch 400 o Resource Hint Name: accept-Patch 402 o Description: Hints the PATCH [RFC5789] request formats accepted by 403 the resource for this client; equivalent to the Accept-Patch HTTP 404 response header. 406 o Specification: [this document] 408 Content MUST be an array of strings, containing media types. 410 When this hint is present, "PATCH" SHOULD be listed in the "allow" 411 hint. 413 5.4. acceptPost 415 o Resource Hint Name: acceptPost 417 o Description: Hints the POST request formats accepted by the 418 resource for this client. 420 o Specification: [this document] 421 Content MUST be an array of strings, containing media types. 423 When this hint is present, "POST" SHOULD be listed in the "allow" 424 hint. 426 5.5. acceptRanges 428 o Resource Hint Name: acceptRanges 430 o Description: Hints the range-specifiers available to the client 431 for this resource; equivalent to the Accept-Ranges HTTP response 432 header [RFC7233]. 434 o Specification: [this document] 436 Content MUST be an array of strings, containing HTTP range-specifiers 437 (typically, "bytes"). 439 5.6. acceptPrefer 441 o Resource Hint Name: acceptPrefer 443 o Description: Hints the preferences [RFC7240] supported by the 444 resource. Note that, as per that specifications, a preference can 445 be ignored by the server. 447 o Specification: [this document] 449 Content MUST be an array of strings, containing preferences. 451 5.7. docs 453 o Resource Hint Name: docs 455 o Description: Hints the location for human-readable documentation 456 for the relation type of the resource. 458 o Specification: [this document] 460 Content MUST be a string containing an absolute-URI [RFC3986] 461 referring to documentation that SHOULD be in HTML format. 463 5.8. preconditionRequired 465 o Resource Hint Name: preconditionRequired 466 o Description: Hints that the resource requires state-changing 467 requests (e.g., PUT, PATCH) to include a precondition, as per 468 [RFC7232], to avoid conflicts due to concurrent updates. 470 o Specification: [this document] 472 Content MUST be an array of strings, with possible values "etag" and 473 "last-modified" indicating type of precondition expected. 475 5.9. authSchemes 477 o Resource Hint Name: authSchemes 479 o Description: Hints that the resource requires authentication using 480 the HTTP Authentication Framework [RFC7235]. 482 o Specification: [this document] 484 Content MUST be an array of objects, each with a "scheme" property 485 containing a string that corresponds to a HTTP authentication scheme, 486 and optionally a "realms" property containing an array of zero to 487 many strings that identify protection spaces that the resource is a 488 member of. 490 For example, a Resource Object might contain the following hint: 492 { 493 "authSchemes": [ 494 { 495 "scheme": "Basic", 496 "realms": ["private"] 497 } 498 ] 499 } 501 5.10. status 503 o Resource Hint Name: status 505 o Description: Hints the status of the resource. 507 o Specification: [this document] 509 Content MUST be a string; possible values are: 511 o "deprecated" - indicates that use of the resource is not 512 recommended, but it is still available. 514 o "gone" - indicates that the resource is no longer available; i.e., 515 it will return a 404 (Not Found) or 410 (Gone) HTTP status code if 516 accessed. 518 6. Security Considerations 520 Clients need to exercise care when using hints. For example, a naive 521 client might send credentials to a server that uses the auth-req 522 hint, without checking to see if those credentials are appropriate 523 for that server. 525 7. IANA Considerations 527 7.1. HTTP Resource Hint Registry 529 This specification defines the HTTP Resource Hint Registry. See 530 Section 5 for a general description of the function of resource 531 hints. 533 In particular, resource hints are generic; that is, they are 534 potentially applicable to any resource, not specific to one 535 application of HTTP, nor to one particular format. Generally, they 536 ought to be information that would otherwise be discoverable by 537 interacting with the resource. 539 Hint names MUST be composed of the lowercase letters (a-z), digits 540 (0-9), underscores ("_") and hyphens ("-"), and MUST begin with a 541 lowercase letter. 543 Hint content SHOULD be described in terms of JSON [RFC7159] 544 constructs. 546 New hints are registered using the Expert Review process described in 547 [RFC5226] to enforce the criteria above. Requests for registration 548 of new resource hints are to use the following template: 550 o Resource Hint Name: [hint name] 552 o Description: [a short description of the hint's semantics] 554 o Specification: [reference to specification document] 556 Initial registrations are enumerated in Section 5. 558 7.2. Media Type Registration 560 TBD 562 8. References 564 8.1. Normative References 566 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 567 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 568 RFC2119, March 1997, 569 . 571 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 572 Resource Identifier (URI): Generic Syntax", STD 66, RFC 573 3986, DOI 10.17487/RFC3986, January 2005, 574 . 576 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 577 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 578 DOI 10.17487/RFC5226, May 2008, 579 . 581 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, DOI 10.17487/ 582 RFC5988, October 2010, 583 . 585 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 586 and D. Orchard, "URI Template", RFC 6570, DOI 10.17487/ 587 RFC6570, March 2012, 588 . 590 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 591 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 592 2014, . 594 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 595 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 596 RFC 7234, DOI 10.17487/RFC7234, June 2014, 597 . 599 8.2. Informative References 601 [RFC4151] Kindberg, T. and S. Hawke, "The 'tag' URI Scheme", RFC 602 4151, DOI 10.17487/RFC4151, October 2005, 603 . 605 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 606 5789, DOI 10.17487/RFC5789, March 2010, 607 . 609 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 610 Specifications and Registration Procedures", BCP 13, RFC 611 6838, DOI 10.17487/RFC6838, January 2013, 612 . 614 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 615 Protocol (HTTP/1.1): Message Syntax and Routing", RFC 616 7230, DOI 10.17487/RFC7230, June 2014, 617 . 619 [RFC7232] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 620 Protocol (HTTP/1.1): Conditional Requests", RFC 7232, DOI 621 10.17487/RFC7232, June 2014, 622 . 624 [RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., 625 "Hypertext Transfer Protocol (HTTP/1.1): Range Requests", 626 RFC 7233, DOI 10.17487/RFC7233, June 2014, 627 . 629 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 630 Protocol (HTTP/1.1): Authentication", RFC 7235, DOI 631 10.17487/RFC7235, June 2014, 632 . 634 [RFC7240] Snell, J., "Prefer Header for HTTP", RFC 7240, DOI 635 10.17487/RFC7240, June 2014, 636 . 638 Appendix A. Acknowledgements 640 Thanks to Jan Algermissen, Mike Amundsen, Bill Burke, Sven Dietze, 641 Graham Klyne, Leif Hedstrom, Joe Hildebrand, Jeni Tennison, Erik 642 Wilde and Jorge Williams for their suggestions and feedback. 644 Appendix B. Considerations for Creating and Serving Home Documents 646 When making an API home document available, there are a few things to 647 keep in mind: 649 o A home document is best located at a memorable URI, because its 650 URI will effectively become the URI for the API itself to clients. 652 o Home documents can be personalized, just as "normal" home pages 653 can. For example, you might advertise different URIs, and/or 654 different kinds of link relations, depending on the client's 655 identity. 657 o Home documents ought to be assigned a freshness lifetime (e.g., 658 "Cache-Control: max-age=3600") so that clients can cache them, to 659 avoid having to fetch it every time the client interacts with the 660 service. 662 o Custom link relation types, as well as the URIs for variables, 663 should lead to documentation for those constructs. 665 B.1. Managing Change in Home Documents 667 The URIs used in API home documents MAY change over time. However, 668 changing them can cause issues for clients that are relying on cached 669 home documents containing old links. 671 To mitigate the impact of such changes, servers ought to consider: 673 o Reducing the freshness lifetime of home documents before a link 674 change, so that clients are less likely to refer to an "old" 675 document. 677 o Regarding the "old" and "new" URIs as equally valid references for 678 an "overlap" period. 680 o After that period, handling requests for the "old" URIs 681 appropriately; e.g., with a 404 Not Found, or by redirecting the 682 client to the new URI. 684 B.2. Evolving and Mixing APIs with Home Documents 686 Using home documents affords the opportunity to change the "shape" of 687 the API over time, without breaking old clients. 689 This includes introducing new functions alongside the old ones - by 690 adding new link relation types with corresponding resource objects - 691 as well as adding new template variables, media types, and so on. 693 It's important to realise that a home document can serve more than 694 one "API" at a time; by listing all relevant relation types, it can 695 effectively "mix" different APIs, allowing clients to work with 696 different resources as they see fit. 698 Appendix C. Considerations for Consuming Home Documents 700 Clients might use home documents in a variety of ways. 702 In the most common case - actually consuming the API - the client 703 will scan the Resources Object for the link relation(s) that it is 704 interested in, and then to interact with the resource(s) referred to. 705 Resource Hints can be used to optimize communication with the client, 706 as well as to inform as to the permissible actions (e.g., whether PUT 707 is likely to be supported). 709 Note that the home document is a "living" document; it does not 710 represent a "contract", but rather is expected to be inspected before 711 each interaction. In particular, links from the home document MUST 712 NOT be assumed to be valid beyond the freshness lifetime of the home 713 document, as per HTTP's caching model [RFC7234]. 715 As a result, clients ought to cache the home document (as per 716 [RFC7234]), to avoid fetching it before every interaction (which 717 would otherwise be required). 719 Likewise, a client encountering a 404 Not Found on a link is 720 encouraged obtain a fresh copy of the home document, to assure that 721 it is up-to-date. 723 Appendix D. Frequently Asked Questions 725 D.1. Why doesn't the format allow references or inheritance? 727 Adding inheritance or references would allow more modularity in the 728 format and make it more compact, at the cost of considerable 729 complexity and the associated potential for errors (both in the 730 specification and by its users). 732 Since good tools and compression are effective ways to achieve the 733 same ends, this specification doesn't attempt them. 735 D.2. What about "Faults" (i.e., errors)? 737 In HTTP, errors are conveyed by HTTP status codes. While this 738 specification could (and even may) allow enumeration of possible 739 error conditions, there's a concern that this will encourage 740 applications to define many such "faults", leading to tight coupling 741 between the application and its clients. 743 D.3. How Do I find the schema for a format? 745 That isn't addressed by home documents. Ultimately, it's up to the 746 media type accepted and generated by resources to define and 747 constrain (or not) their syntax. 749 D.4. How do I express complex query arguments? 751 Complex queries - i.e., those that exceed the expressive power of 752 Link Templates or would require ambiguous properties of a "resources" 753 object - aren't intended to be defined by a home document. The 754 appropriate way to do this is with a "form" language, much as HTML 755 defines. 757 Note that it is possible to support multiple query syntaxes on the 758 same base URL, using more than one link relation type; see the 759 example at the start of the document. 761 Author's Address 763 Mark Nottingham 765 Email: mnot@mnot.net 766 URI: https://www.mnot.net/