idnits 2.17.00 (12 Aug 2021) /tmp/idnits19316/draft-nottingham-json-home-06.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 (February 15, 2017) is 1914 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 February 15, 2017 4 Intended status: Informational 5 Expires: August 19, 2017 7 Home Documents for HTTP APIs 8 draft-nottingham-json-home-06 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 August 19, 2017. 46 Copyright Notice 48 Copyright (c) 2017 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 . . . . . . . . . . . . . . . . . . . . . . . . . 7 67 4. Resource Objects . . . . . . . . . . . . . . . . . . . . . . 7 68 4.1. Resolving Templated Links . . . . . . . . . . . . . . . . 8 69 5. Resource Hints . . . . . . . . . . . . . . . . . . . . . . . 8 70 5.1. allow . . . . . . . . . . . . . . . . . . . . . . . . . . 9 71 5.2. formats . . . . . . . . . . . . . . . . . . . . . . . . . 9 72 5.3. acceptPatch . . . . . . . . . . . . . . . . . . . . . . . 9 73 5.4. acceptPost . . . . . . . . . . . . . . . . . . . . . . . 10 74 5.5. acceptPut . . . . . . . . . . . . . . . . . . . . . . . . 10 75 5.6. acceptRanges . . . . . . . . . . . . . . . . . . . . . . 10 76 5.7. acceptPrefer . . . . . . . . . . . . . . . . . . . . . . 11 77 5.8. docs . . . . . . . . . . . . . . . . . . . . . . . . . . 11 78 5.9. preconditionRequired . . . . . . . . . . . . . . . . . . 11 79 5.10. authSchemes . . . . . . . . . . . . . . . . . . . . . . . 11 80 5.11. status . . . . . . . . . . . . . . . . . . . . . . . . . 12 81 6. Security Considerations . . . . . . . . . . . . . . . . . . . 12 82 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 83 7.1. HTTP Resource Hint Registry . . . . . . . . . . . . . . . 12 84 7.2. Media Type Registration . . . . . . . . . . . . . . . . . 13 85 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 86 8.1. Normative References . . . . . . . . . . . . . . . . . . 13 87 8.2. Informative References . . . . . . . . . . . . . . . . . 14 88 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 15 89 Appendix B. Creating and Serving Home Documents . . . . . . . . 15 90 B.1. Managing Change in Home Documents . . . . . . . . . . . . 15 91 B.2. Evolving and Mixing APIs with Home Documents . . . . . . 16 92 Appendix C. Consuming Home Documents . . . . . . . . . . . . . . 16 93 Appendix D. Frequently Asked Questions . . . . . . . . . . . . . 17 94 D.1. Why not use (insert other service description format)? . 17 95 D.2. Why doesn't the format allow references or inheritance? . 17 96 D.3. What about "Faults" (i.e., errors)? . . . . . . . . . . . 17 97 D.4. How Do I find the schema for a format? . . . . . . . . . 17 98 D.5. How do I express complex query arguments? . . . . . . . . 17 99 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 18 101 1. Introduction 103 It is becoming increasingly common to use HTTP [RFC7230] for 104 applications other than traditional Web browsing. Such "HTTP APIs" 105 are used to integrate processes on disparate systems, make 106 information available to machines across the Internet, and as part of 107 the implementation of "micro-services." 109 By using HTTP, these applications realise a number of benefits, from 110 message framing to caching, and well-defined semantics that are 111 broadly understood and useful. 113 Often, these applications of HTTP are defined by documenting static 114 URLs that clients need to know and servers need to implement. Any 115 interaction outside of these bounds is uncharted territory. 117 For some applications, this approach brings issues, especially when 118 the interface changes, either due to evolution, extension or drift 119 between implementations. Furthermore, implementing more than one 120 instance of interface can bring further issues, as different 121 environments have different requirements. 123 The Web itself offers one way to address these issues, using links 124 [RFC3986] to navigate between states. A link-driven application 125 discovers relevant resources at run time, using a shared vocabulary 126 of link relations [RFC5988] and internet media types [RFC6838] to 127 support a "follow your nose" style of interaction - just as a Web 128 browser does to navigate the Web. 130 A client can then decide which resources to interact with "on the 131 fly" based upon its capabilities (as described by link relations), 132 and the server can safely add new resources and formats without 133 disturbing clients that are not yet aware of them. 135 Doing so can provide any of a number of benefits, including: 137 o Extensibility - Because new server capabilities can be expressed 138 as link relations, new features can be layered in without 139 introducing a new API version; clients will discover them in the 140 home document. This promotes loose coupling between clients and 141 servers. 143 o Evolvability - Likewise, interfaces can change gradually by 144 introducing a new link relation and/or format while still 145 supporting the old ones. 147 o Customisation - Home documents can be tailored for the client, 148 allowing diffrent classes of service or different client 149 permissions to be exposed naturally. 151 o Flexible deployment - Since URLs aren't baked into documentation, 152 the server can choose what URLs to use for a given service. 154 o API mixing - Likewise, more than one API can be deployed on a 155 given server, without fear of collisions. 157 Whether an application ought to use links in this fashion depends on 158 how it is deployed; generally, the most benefit will be received when 159 multiple instances of the service are deployed, possibly with 160 different versions, and they are consumed by clients with different 161 capabilities. In particular, Internet Standards that use HTTP as a 162 substrate are likely to require the attributes described above. 164 This document defines a "home page" format using the JSON format 165 [RFC7159] for APIs to use as a launching point for the interactions 166 they offer, using links. Having a well-defined format for this 167 purpose promotes good practice and tooling. 169 1.1. Notational Conventions 171 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 172 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 173 document are to be interpreted as described in [RFC2119]. 175 2. API Home Documents 177 An API Home Document (or, interchangeably, "home document") uses the 178 format described in [RFC7159] and has the media type "application/ 179 json-home". 181 *Note: this media type is not final, and will change before final 182 publication.* 184 Its content consists of a root object with: 186 o A "resources" member, whose value is an object that describes the 187 resources associated with the API. Its member names are link 188 relation types (as defined by [RFC5988]), and their values are 189 Resource Objects (Section 4). 191 o Optionally, a "api" member, whose value is an API Object 192 (Section 3) that contains information about the API as a whole. 194 For example: 196 GET / HTTP/1.1 197 Host: example.org 198 Accept: application/json-home 200 HTTP/1.1 200 OK 201 Content-Type: application/json-home 202 Cache-Control: max-age=3600 203 Connection: close 205 { 206 "api": { 207 "title": "Example API", 208 "links": { 209 "author": "mailto:api-admin@example.com", 210 "describedBy": "https://example.com/api-docs/" 211 } 212 } 213 "resources": { 214 "tag:me@example.com,2016:widgets": { 215 "href": "/widgets/" 216 }, 217 "tag:me@example.com,2016:widget": { 218 "hrefTemplate": "/widgets/{widget_id}", 219 "hrefVars": { 220 "widget_id": "https://example.org/param/widget" 221 }, 222 "hints": { 223 "allow": ["GET", "PUT", "DELETE", "PATCH"], 224 "formats": { 225 "application/json": {} 226 }, 227 "acceptPatch": ["application/json-patch+json"], 228 "acceptRanges": ["bytes"] 229 } 230 } 231 } 232 } 234 Here, we have a home document for the API "Example API", whose author 235 can be contacted at the e-mail address "api-admin@example.com", and 236 whose documentation is at "https://example.com/api-docs/". 238 It links to a resource "/widgets/" with the relation 239 "tag:me@example.com,2016:widgets". It also links to an unknown 240 number of resources with the relation type 241 "tag:me@example.com,2016:widget" using a URI Template [RFC6570], 242 along with a mapping of identifiers to a variable for use in that 243 template. 245 It also gives several hints about interacting with the latter 246 "widget" resources, including the HTTP methods usable with them, the 247 PATCH and POST formats they accept, and the fact that they support 248 partial requests [RFC7233] using the "bytes" range-specifier. 250 It gives no such hints about the "widgets" resource. This does not 251 mean that it (for example) doesn't support any HTTP methods; it means 252 that the client will need to discover this by interacting with the 253 resource, and/or examining the documentation for its link relation 254 type. 256 Effectively, this names a set of behaviors, as described by a 257 resource object, with a link relation type. This means that several 258 link relations might apply to a common base URL; e.g.: 260 { 261 "resources": { 262 "tag:me@example.com,2016:search-by-id": { 263 "hrefTemplate": "/search?id={widget_id}", 264 "hrefVars": { 265 "widget_id": "https://example.org/param/widget_id" 266 } 267 }, 268 "tag:me@example.com,2016:search-by-name": { 269 "hrefTemplate": "/search?name={widget_name}", 270 "hrefVars": { 271 "widget_name": "https://example.org/param/widget_name" 272 } 273 } 274 } 275 } 277 Note that the examples above use both tag [RFC4151] and https 278 [RFC7230] URIs; any URI scheme can be used to identify link relations 279 and other artefacts in home documents. Typically, these are not 280 links to be followed; they are only used to identify things. 282 3. API Objects 284 An API Object contains links to information about the API itself. 286 Two optional members are defined: 288 o "title" has a string value indicating the name of the API; 290 o "links" has an object value, whose member names are link relation 291 types [RFC5988], and values are URLs [RFC3986]. The context of 292 these links is the API home document as a whole. 294 No links are required to be conveyed, but APIs might benefit from 295 setting the following: 297 o author - a suitable URL (e.g., mailto: or https:) for the 298 author(s) of the API 300 o describedBy - a link to documentation for the API 302 o license - a link to the legal terms for using the API 304 Future members of the API Object MAY be defined by specifications 305 that update this document. 307 4. Resource Objects 309 A Resource Object links to resources of the type indicated in their 310 name using one of two mechanisms; either a direct link (in which case 311 there is exactly one resource of that relation type associated with 312 the API), or a templated link, in which case there are zero to many 313 such resources. 315 Direct links are indicated with an "href" property, whose value is a 316 URI [RFC3986]. 318 Templated links are indicated with an "hrefTemplate" property, whose 319 value is a URI Template [RFC6570]. When "hrefTemplate" is present, 320 the Resource Object MUST have a "hrefVars" property; see "Resolving 321 Templated Links". 323 Resource Objects MUST have exactly one of the "href" or "href-vars" 324 properties. 326 In both forms, the links that "href" and "hrefTemplate" refer to are 327 URI-references [RFC3986] whose base URI is that of the API Home 328 Document itself. 330 Resource Objects MAY also have a "hints" property, whose value is an 331 object that uses named Resource Hints (see Section 5) as its 332 properties. 334 4.1. Resolving Templated Links 336 A URI can be derived from a Templated Link by treating the 337 "hrefTemplate" value as a Level 3 URI Template [RFC6570], using the 338 "hrefVars" property to fill the template. 340 The "hrefVars" property, in turn, is an object that acts as a mapping 341 between variable names available to the template and absolute URIs 342 that are used as global identifiers for the semantics and syntax of 343 those variables. 345 For example, given the following Resource Object: 347 "https://example.org/rel/widget": { 348 "hrefTemplate": "/widgets/{widget_id}", 349 "hrefVars": { 350 "widget_id": "https://example.org/param/widget" 351 }, 352 "hints": { 353 "allow": ["GET", "PUT", "DELETE", "PATCH"], 354 "formats": { 355 "application/json": {} 356 }, 357 "acceptPatch": ["application/json-patch+json"], 358 "acceptRanges": ["bytes"] 359 } 360 } 362 If you understand that "https://example.org/param/widget" is an 363 numeric identifier for a widget, you can then find the resource 364 corresponding to widget number 12345 at "https://example.org/ 365 widgets/12345" (assuming that the Home Document is located at 366 "https://example.org/"). 368 5. Resource Hints 370 Resource hints allow clients to find relevant information about 371 interacting with a resource beforehand, as a means of optimizing 372 communications, as well as advertising available behaviors (e.g., to 373 aid in laying out a user interface for consuming the API). 375 Hints are just that - they are not a "contract", and are to only be 376 taken as advisory. The runtime behavior of the resource always 377 overrides hinted information. 379 For example, a resource might hint that the PUT method is allowed on 380 all "widget" resources. This means that generally, the user has the 381 ability to PUT to a particular resource, but a specific resource 382 might reject a PUT based upon access control or other considerations. 383 More fine-grained information might be gathered by interacting with 384 the resource (e.g., via a GET), or by another resource "containing" 385 it (such as a "widgets" collection) or describing it (e.g., one 386 linked to it with a "describedBy" link relation). 388 This specification defines a set of common hints, based upon 389 information that's discoverable by directly interacting with 390 resources. See Section 7.1 for information on defining new hints. 392 5.1. allow 394 o Resource Hint Name: allow 396 o Description: Hints the HTTP methods that the current client will 397 be able to use to interact with the resource; equivalent to the 398 Allow HTTP response header. 400 o Specification: [this document] 402 Content MUST be an array of strings, containing HTTP methods. As per 403 HTTP, when GET is supported, a client MAY assume that HEAD is 404 supported. 406 5.2. formats 408 o Resource Hint Name: formats 410 o Description: Hints the representation types that the resource 411 makes available, using the GET method. 413 o Specification: [this document] 415 Content MUST be an object, whose keys are media types, and values are 416 objects, currently empty. 418 5.3. acceptPatch 420 o Resource Hint Name: accept-Patch 422 o Description: Hints the PATCH [RFC5789] request formats accepted by 423 the resource for this client; equivalent to the Accept-Patch HTTP 424 response header. 426 o Specification: [this document] 427 Content MUST be an array of strings, containing media types. 429 When this hint is present, "PATCH" SHOULD be listed in the "allow" 430 hint. 432 5.4. acceptPost 434 o Resource Hint Name: acceptPost 436 o Description: Hints the POST request formats accepted by the 437 resource for this client. 439 o Specification: [this document] 441 Content MUST be an array of strings, containing media types. 443 When this hint is present, "POST" SHOULD be listed in the "allow" 444 hint. 446 5.5. acceptPut 448 o Resource Hint Name: acceptPut 450 o Description: Hints the PUT request formats accepted by the 451 resource for this client. 453 o Specification: [this document] 455 Content MUST be an array of strings, containing media types. 457 When this hint is present, "PUT" SHOULD be listed in the "allow" 458 hint. 460 5.6. acceptRanges 462 o Resource Hint Name: acceptRanges 464 o Description: Hints the range-specifiers available to the client 465 for this resource; equivalent to the Accept-Ranges HTTP response 466 header [RFC7233]. 468 o Specification: [this document] 470 Content MUST be an array of strings, containing HTTP range-specifiers 471 (typically, "bytes"). 473 5.7. acceptPrefer 475 o Resource Hint Name: acceptPrefer 477 o Description: Hints the preferences [RFC7240] supported by the 478 resource. Note that, as per that specifications, a preference can 479 be ignored by the server. 481 o Specification: [this document] 483 Content MUST be an array of strings, containing preferences. 485 5.8. docs 487 o Resource Hint Name: docs 489 o Description: Hints the location for human-readable documentation 490 for the relation type of the resource. 492 o Specification: [this document] 494 Content MUST be a string containing an absolute-URI [RFC3986] 495 referring to documentation that SHOULD be in HTML format. 497 5.9. preconditionRequired 499 o Resource Hint Name: preconditionRequired 501 o Description: Hints that the resource requires state-changing 502 requests (e.g., PUT, PATCH) to include a precondition, as per 503 [RFC7232], to avoid conflicts due to concurrent updates. 505 o Specification: [this document] 507 Content MUST be an array of strings, with possible values "etag" and 508 "last-modified" indicating type of precondition expected. 510 5.10. authSchemes 512 o Resource Hint Name: authSchemes 514 o Description: Hints that the resource requires authentication using 515 the HTTP Authentication Framework [RFC7235]. 517 o Specification: [this document] 519 Content MUST be an array of objects, each with a "scheme" property 520 containing a string that corresponds to a HTTP authentication scheme, 521 and optionally a "realms" property containing an array of zero to 522 many strings that identify protection spaces that the resource is a 523 member of. 525 For example, a Resource Object might contain the following hint: 527 { 528 "authSchemes": [ 529 { 530 "scheme": "Basic", 531 "realms": ["private"] 532 } 533 ] 534 } 536 5.11. status 538 o Resource Hint Name: status 540 o Description: Hints the status of the resource. 542 o Specification: [this document] 544 Content MUST be a string; possible values are: 546 o "deprecated" - indicates that use of the resource is not 547 recommended, but it is still available. 549 o "gone" - indicates that the resource is no longer available; i.e., 550 it will return a 404 (Not Found) or 410 (Gone) HTTP status code if 551 accessed. 553 6. Security Considerations 555 Clients need to exercise care when using hints. For example, a naive 556 client might send credentials to a server that uses the auth-req 557 hint, without checking to see if those credentials are appropriate 558 for that server. 560 7. IANA Considerations 562 7.1. HTTP Resource Hint Registry 564 This specification defines the HTTP Resource Hint Registry. See 565 Section 5 for a general description of the function of resource 566 hints. 568 In particular, resource hints are generic; that is, they are 569 potentially applicable to any resource, not specific to one 570 application of HTTP, nor to one particular format. Generally, they 571 ought to be information that would otherwise be discoverable by 572 interacting with the resource. 574 Hint names MUST be composed of the lowercase letters (a-z), digits 575 (0-9), underscores ("_") and hyphens ("-"), and MUST begin with a 576 lowercase letter. 578 Hint content SHOULD be described in terms of JSON [RFC7159] 579 constructs. 581 New hints are registered using the Expert Review process described in 582 [RFC5226] to enforce the criteria above. Requests for registration 583 of new resource hints are to use the following template: 585 o Resource Hint Name: [hint name] 587 o Description: [a short description of the hint's semantics] 589 o Specification: [reference to specification document] 591 Initial registrations are enumerated in Section 5. 593 7.2. Media Type Registration 595 TBD 597 8. References 599 8.1. Normative References 601 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 602 Requirement Levels", BCP 14, RFC 2119, 603 DOI 10.17487/RFC2119, March 1997, 604 . 606 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 607 Resource Identifier (URI): Generic Syntax", STD 66, 608 RFC 3986, DOI 10.17487/RFC3986, January 2005, 609 . 611 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 612 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 613 DOI 10.17487/RFC5226, May 2008, 614 . 616 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 617 DOI 10.17487/RFC5988, October 2010, 618 . 620 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 621 and D. Orchard, "URI Template", RFC 6570, 622 DOI 10.17487/RFC6570, March 2012, 623 . 625 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 626 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 627 2014, . 629 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 630 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 631 RFC 7234, DOI 10.17487/RFC7234, June 2014, 632 . 634 8.2. Informative References 636 [RFC4151] Kindberg, T. and S. Hawke, "The 'tag' URI Scheme", 637 RFC 4151, DOI 10.17487/RFC4151, October 2005, 638 . 640 [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", 641 RFC 5789, DOI 10.17487/RFC5789, March 2010, 642 . 644 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 645 Specifications and Registration Procedures", BCP 13, 646 RFC 6838, DOI 10.17487/RFC6838, January 2013, 647 . 649 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 650 Protocol (HTTP/1.1): Message Syntax and Routing", 651 RFC 7230, DOI 10.17487/RFC7230, June 2014, 652 . 654 [RFC7232] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 655 Protocol (HTTP/1.1): Conditional Requests", RFC 7232, 656 DOI 10.17487/RFC7232, June 2014, 657 . 659 [RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., 660 "Hypertext Transfer Protocol (HTTP/1.1): Range Requests", 661 RFC 7233, DOI 10.17487/RFC7233, June 2014, 662 . 664 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 665 Protocol (HTTP/1.1): Authentication", RFC 7235, 666 DOI 10.17487/RFC7235, June 2014, 667 . 669 [RFC7240] Snell, J., "Prefer Header for HTTP", RFC 7240, 670 DOI 10.17487/RFC7240, June 2014, 671 . 673 [RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP 674 APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016, 675 . 677 Appendix A. Acknowledgements 679 Thanks to Jan Algermissen, Mike Amundsen, Bill Burke, Sven Dietze, 680 Graham Klyne, Leif Hedstrom, Joe Hildebrand, Jeni Tennison, Erik 681 Wilde and Jorge Williams for their suggestions and feedback. 683 Appendix B. Creating and Serving Home Documents 685 When making an API home document available, there are a few things to 686 keep in mind: 688 o A home document is best located at a memorable URI, because its 689 URI will effectively become the URI for the API itself to clients. 691 o Home documents can be personalized, just as "normal" home pages 692 can. For example, you might advertise different URIs, and/or 693 different kinds of link relations, depending on the client's 694 identity. 696 o Home documents ought to be assigned a freshness lifetime (e.g., 697 "Cache-Control: max-age=3600") so that clients can cache them, to 698 avoid having to fetch it every time the client interacts with the 699 service. 701 o Custom link relation types, as well as the URIs for variables, 702 should lead to documentation for those constructs. 704 B.1. Managing Change in Home Documents 706 The URIs used in API home documents MAY change over time. However, 707 changing them can cause issues for clients that are relying on cached 708 home documents containing old links. 710 To mitigate the impact of such changes, servers ought to consider: 712 o Reducing the freshness lifetime of home documents before a link 713 change, so that clients are less likely to refer to an "old" 714 document. 716 o Regarding the "old" and "new" URIs as equally valid references for 717 an "overlap" period. 719 o After that period, handling requests for the "old" URIs 720 appropriately; e.g., with a 404 Not Found, or by redirecting the 721 client to the new URI. 723 B.2. Evolving and Mixing APIs with Home Documents 725 Using home documents affords the opportunity to change the "shape" of 726 the API over time, without breaking old clients. 728 This includes introducing new functions alongside the old ones - by 729 adding new link relation types with corresponding resource objects - 730 as well as adding new template variables, media types, and so on. 732 It's important to realise that a home document can serve more than 733 one "API" at a time; by listing all relevant relation types, it can 734 effectively "mix" different APIs, allowing clients to work with 735 different resources as they see fit. 737 Appendix C. Consuming Home Documents 739 Clients might use home documents in a variety of ways. 741 In the most common case - actually consuming the API - the client 742 will scan the Resources Object for the link relation(s) that it is 743 interested in, and then to interact with the resource(s) referred to. 744 Resource Hints can be used to optimize communication with the client, 745 as well as to inform as to the permissible actions (e.g., whether PUT 746 is likely to be supported). 748 Note that the home document is a "living" document; it does not 749 represent a "contract", but rather is expected to be inspected before 750 each interaction. In particular, links from the home document MUST 751 NOT be assumed to be valid beyond the freshness lifetime of the home 752 document, as per HTTP's caching model [RFC7234]. 754 As a result, clients ought to cache the home document (as per 755 [RFC7234]), to avoid fetching it before every interaction (which 756 would otherwise be required). 758 Likewise, a client encountering a 404 (Not Found) on a link is 759 encouraged obtain a fresh copy of the home document, to assure that 760 it is up-to-date. 762 Appendix D. Frequently Asked Questions 764 D.1. Why not use (insert other service description format)? 766 There are a fair number of existing service description formats, 767 including those that specialise in "RESTful" interactions. However, 768 these formats generally are optimised for pairwise integration, or 769 one-server-to-many-client integration, and less capable of describing 770 protocols where both the server and client can evolve and be 771 extended. 773 D.2. Why doesn't the format allow references or inheritance? 775 Adding inheritance or references would allow more modularity in the 776 format and make it more compact, at the cost of considerable 777 complexity and the associated potential for errors (both in the 778 specification and by its users). 780 Since good tools and compression are effective ways to achieve the 781 same ends, this specification doesn't attempt them. 783 D.3. What about "Faults" (i.e., errors)? 785 In HTTP, errors are conveyed by HTTP status codes. While this 786 specification could (and even may) allow enumeration of possible 787 error conditions, there's a concern that this will encourage 788 applications to define many such "faults", leading to tight coupling 789 between the application and its clients. See [RFC7807] for further 790 considerations. 792 D.4. How Do I find the schema for a format? 794 That isn't addressed by home documents. Ultimately, it's up to the 795 media type accepted and generated by resources to define and 796 constrain (or not) their syntax. 798 D.5. How do I express complex query arguments? 800 Complex queries - i.e., those that exceed the expressive power of 801 Link Templates or would require ambiguous properties of a "resources" 802 object - aren't intended to be defined by a home document. The 803 appropriate way to do this is with a "form" language, much as HTML 804 defines. 806 Note that it is possible to support multiple query syntaxes on the 807 same base URL, using more than one link relation type; see the 808 example at the start of the document. 810 Author's Address 812 Mark Nottingham 814 Email: mnot@mnot.net 815 URI: https://www.mnot.net/