Network Working Group                                      M. Nottingham
Internet-Draft                                              May 23,                                         November 24, 2016
Intended status: Informational
Expires: November 24, 2016 May 28, 2017

                      Home Documents for HTTP APIs
                     draft-nottingham-json-home-04
                     draft-nottingham-json-home-05

Abstract

   This document proposes a "home document" format for non-browser HTTP
   clients.

Note to Readers

   The issues list for this draft can be found at
   https://github.com/mnot/I-D/labels/json-home .

   The most recent (often, unpublished) draft is at
   https://mnot.github.io/I-D/json-home/ .

   Recent changes are listed at https://github.com/mnot/I-D/commits/gh-
   pages/json-home .

   For information about implementations, see https://github.com/mnot/I-
   D/wiki/json-home .

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on November 24, 2016. May 28, 2017.

Copyright Notice

   Copyright (c) 2016 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
     1.1.  Notational Conventions  . . . . . . . . . . . . . . . . .   4
   2.  JSON  API Home Documents  . . . . . . . . . . . . . . . . . . . . .   4
   3.  Resource  API Objects . . . . . . . . . . . . . . . . . . . . . .   5
     3.1.  Resolving Templated Links . . . . . . . . . . . . . . . .   6
   4.  Resource Hints  . Objects  . . . . . . . . . . . . . . . . . . . . . .   7
     4.1.  allow . . . . .  Resolving Templated Links . . . . . . . . . . . . . . . .   7
   5.  Resource Hints  . . . . .   8
     4.2.  formats . . . . . . . . . . . . . . . . . .   8
     5.1.  allow . . . . . . .   8
     4.3.  accept-patch . . . . . . . . . . . . . . . . . . .   9
     5.2.  formats . . .   8
     4.4.  accept-post . . . . . . . . . . . . . . . . . . . . . .   9
     5.3.  acceptPatch .   8
     4.5.  accept-ranges . . . . . . . . . . . . . . . . . . . . . .   9
     4.6.  accept-prefer
     5.4.  acceptPost  . . . . . . . . . . . . . . . . . . . . . . .   9
     4.7.  docs
     5.5.  acceptRanges  . . . . . . . . . . . . . . . . . . . . . .  10
     5.6.  acceptPrefer  . . . .   9
     4.8.  precondition-req . . . . . . . . . . . . . . . . . .  10
     5.7.  docs  . .   9
     4.9.  auth-req . . . . . . . . . . . . . . . . . . . . . . . .  10
     4.10. status  . . .
     5.8.  preconditionRequired  . . . . . . . . . . . . . . . . . .  10
     5.9.  authSchemes . . . .  10
   5.  Representation Hints  . . . . . . . . . . . . . . . . . . . .  11
   6.  Creating and Serving Home Documents
     5.10. status  . . . . . . . . . . . . .  11
     6.1.  Managing Change in Home Documents . . . . . . . . . . . .  11
     6.2.  Evolving and Mixing APIs with Home Documents
   6.  Security Considerations . . . . . .  12
     6.3.  Documenting APIs that use Home Documents . . . . . . . .  12
   7.  Consuming Home Documents . . . . .  12
   7.  IANA Considerations . . . . . . . . . . . . .  12
   8.  Security Considerations . . . . . . . .  12
     7.1.  HTTP Resource Hint Registry . . . . . . . . . . .  13
   9.  IANA Considerations . . . .  12
     7.2.  Media Type Registration . . . . . . . . . . . . . . . . .  13
     9.1.  HTTP Resource Hint Registry
   8.  References  . . . . . . . . . . . . . . .  13
     9.2.  HTTP Representation Hint Registry . . . . . . . . . . . .  13
     9.3.  Media Type Registration . .
     8.1.  Normative References  . . . . . . . . . . . . . . .  14
   10. References  . . . .  13
     8.2.  Informative References  . . . . . . . . . . . . . . . . .  13
   Appendix A.  Acknowledgements . . . .  14
     10.1.  Normative References . . . . . . . . . . . . . .  14
   Appendix B.  Considerations for Creating and Serving Home
                Documents  . . . .  14
     10.2.  Informative References . . . . . . . . . . . . . . . . .  14
   Appendix A.  Acknowledgements
     B.1.  Managing Change in Home Documents . . . . . . . . . . . .  15
     B.2.  Evolving and Mixing APIs with Home Documents  . . . . . .  15
   Appendix B.  Frequently Asked Questions . . . . . . . . . C.  Considerations for Consuming Home Documents  . . . .  16
     B.1.  Why not Microformats? . . . . .
   Appendix D.  Frequently Asked Questions . . . . . . . . . . . . .  16
     B.2.
     D.1.  Why doesn't the format allow references or inheritance? .  16
     B.3.  What about authentication?  . . . . . . . . . . . . . . .  16
     B.4.
     D.2.  What about "Faults" (i.e., errors)? . . . . . . . . . . .  16
     B.5.
     D.3.  How Do I find the schema for a format?  . . . . . . . . .  17
     B.6.
     D.4.  How do I express complex query arguments? . . . . . . . .  17
   Appendix C.  Open Issues  . . . . . . . . . . . . . . . . . . . .  17
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .  18  17

1.  Introduction

   There

   It is an emerging preference becoming increasingly common to use HTTP [RFC7230] for non-browser Web
   applications
   (colloquially, other than traditional Web browsing.  Such "HTTP APIs") to use a link-driven approach APIs"
   are used to their
   interactions integrate processes on disparate systems, make
   information available to assure loose coupling, thereby enabling extensibility machines across the Internet, and API evolution.

   This is based upon experience with previous APIs that specified
   static URI paths (such as
   "http://api.example.com/v1.0/widgets/abc123/properties"), which have
   resulted in brittle, tight coupling between clients and servers.

   Sometimes, part of
   the implementation of "micro-services."

   By using HTTP, these APIs are documented by applications realise a document format like [WADL] number of benefits, from
   message framing to caching, and well-defined semantics that are
   broadly understood and useful.

   However, one of the core architectural tenants of the Web is used as a design-time description; i.e., the URIs use
   of links [RFC3986] to navigate between states; typically, these
   applications document static URLs that clients need to know and other
   information they describe are "baked into" client implementations.
   servers need to implement, and any interaction outside of these
   bounds is uncharted territory.

   In contrast, a "follow your nose" API advertises the link-driven application discovers relevant resources
   available to clients
   at run time, using a shared vocabulary of link relations [RFC5988]
   and the formats
   they support using internet media types [RFC6838]. [RFC6838] to support a "follow your nose"
   style of interaction.

   A client can then decide - at run time - which resources to interact with "on the
   fly" based upon its capabilities (as described by link relations),
   and the server can safely add new resources and formats without
   disturbing clients that are not yet aware of them.

   As such,

   Doing so can provide any of a number of benefits, including:

   o  Extensibility - Because new server capabilities can be expressed
      as link relations, new features can be layered in without
      introducing a new API version; clients will discover them in the
      home document.  This promotes loose coupling between clients and
      servers.

   o  Evolvability - Likewise, interfaces can change gradually by
      introducing a new link relation and/or format while still
      supporting the old ones.

   o  Customisation - Home documents can be tailored for the client,
      allowing diffrent classes of service or different client
      permissions to be exposed naturally.

   o  Flexible deployment - Since URLs aren't baked into documentation,
      the server can choose what URLs to use for a given service.

   o  API mixing - Likewise, more than one API can be deployed on a
      given server, without fear of collisions.

   Whether an application ought to use links in this fashion depends on
   how it is deployed; generally, the most benefit will be received when
   multiple instances of the service are deployed, possibly with
   different versions, and they are consumed by clients with different
   capabilities.  In particular, Internet Standards that use HTTP as a
   substrate are likely to require the attributes described above.

   Clients need to be able to discover this information quickly
   and efficiently about these
   applications to use it to interact with the server.  Just efficiently; just as with a human-targeted
   "home page" for a site, we can create there is a need for a "home document" for a
   HTTP API that describes it to non-browser clients.

   Of course, an HTTP API might use any format to do so; however, there
   are advantages to having a standard common home document format.  This
   specification suggests one for consideration, defines one, using t he the JSON format [RFC7159].

1.1.  Notational Conventions

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [RFC2119].

2.  JSON  API Home Documents

   A JSON

   An API Home Document (or, interchangeably, "home document") uses the
   format described in [RFC7159] and has the media type "application/json-home". "application/
   json-home".

   Its content consists of a root object with a with:

   o  A "resources" property, member, whose value is an object that describes the
      resources associated with the API.  Its member names are link
      relation types (as defined by [RFC5988]), and their values are
      Resource Objects, defined below. Objects (Section 4).

   o  Optionally, a "api" member, whose value is an API Object
      (Section 3) that contains information about the API as a whole.

   For example:

     GET / HTTP/1.1
     Host: example.org
     Accept: application/json-home

     HTTP/1.1 200 OK
     Content-Type: application/json-home
     Cache-Control: max-age=3600
     Connection: close

     {
       "api": {
         "title": "Example API",
         "links": {
           "author": "mailto:api-admin@example.com",
           "describedBy": "https://example.com/api-docs/"
         }
       }
       "resources": {
         "tag:me@example.com,2016:widgets": {
           "href": "/widgets/"
         },
         "tag:me@example.com,2016:widget": {
           "href-template":
           "hrefTemplate": "/widgets/{widget_id}",
           "href-vars":
           "hrefVars": {
             "widget_id": "http://example.org/param/widget" "https://example.org/param/widget"
           },
           "hints": {
             "allow": ["GET", "PUT", "DELETE", "PATCH"],
             "formats": {
               "application/json": {}
             },
             "accept-patch":
             "acceptPatch": ["application/json-patch+json"],
             "accept-post": ["application/xml"],
             "accept-ranges":
             "acceptRanges": ["bytes"]
           }
         }
       }
     }

   Here, we have a home document that for the API "Example API", whose author
   can be contacted at the e-mail address "api-admin@example.com", and
   whose documentation is at "https://example.com/api-docs/".

   It links to a resource, resource "/widgets/" with the relation
   "tag:me@example.com,2016:widgets".  It also links to an unknown
   number of resources with the relation type
   "tag:me@example.com,2016:widget" using a URI Template [RFC6570],
   along with a mapping of identifiers to a variable for use in that
   template.

   It also gives several hints about interacting with the latter
   "widget" resources, including the HTTP methods usable with them, the
   patch
   PATCH and POST formats they accept, and the fact that they support
   partial requests [RFC7233] using the "bytes" range-specifier.

   It gives no such hints about the "widgets" resource.  This does not
   mean that it (for example) doesn't support any HTTP methods; it means
   that the client will need to discover this by interacting with the
   resource, and/or examining the documentation for its link relation
   type.

   Effectively, this names a set of behaviors, as described by a
   resource object, with a link relation type.  This means that several
   link relations might apply to a common base URL; e.g.:

   {
     "resources": {
       "tag:me@example.com,2016:search-by-id": {
         "href-template":
         "hrefTemplate": "/search?id={widget_id}",
         "href-vars":
         "hrefVars": {
           "widget_id": "http://example.org/param/widget_id" "https://example.org/param/widget_id"
         }
       },
       "tag:me@example.com,2016:search-by-name": {
         "href-template":
         "hrefTemplate": "/search?name={widget_name}",
         "href-vars":
         "hrefVars": {
           "widget_name": "http://example.org/param/widget_name" "https://example.org/param/widget_name"
         }
       }
     }
   }

   Note that the examples above use both tag [RFC4151] and http https
   [RFC7230] URIs; any URI scheme can be used to identify link relations
   and other artefacts in home documents.

3.  API Objects

   An API Object contains links to information about the API itself.

   Two members are defined:

   o  "title" has a string value indicating the name of the API;
   o  "links" has an object value, whose member names are link relation
      types [RFC5988], and values are URLs [RFC3986].  The context of
      these links is the API home document as a whole.

   Future members MAY be defined by specifications that update this
   document.

4.  Resource Objects

   A Resource Object links to resources of the defined type using one of
   two mechanisms; either a direct link (in which case there is exactly
   one resource of that relation type associated with the API), or a
   templated link, in which case there are zero to many such resources.

   Direct links are indicated with an "href" property, whose value is a
   URI [RFC3986].

   Templated links are indicated with an "href-template" "hrefTemplate" property, whose
   value is a URI Template [RFC6570].  When "href-template" "hrefTemplate" is present,
   the Resource Object MUST have a "href-vars" "hrefVars" property; see "Resolving
   Templated Links".

   Resource Objects MUST have exactly one of the "href" and "href-vars"
   properties.

   In both forms, the links that "href" and "href-template" "hrefTemplate" refer to are
   URI-references [RFC3986] whose base URI is that of the JSON API Home
   Document itself.

   Resource Objects MAY also have a "hints" property, whose value is an
   object that uses named Resource Hints (see Section 4) 5) as its
   properties.

3.1.

4.1.  Resolving Templated Links

   A URI can be derived from a Templated Link by treating the "href-
   template"
   "hrefTemplate" value as a Level 3 URI Template [RFC6570], using the "href-
   vars"
   "hrefVars" property to fill the template.

   The "href-vars" "hrefVars" property, in turn, is an object that acts as a mapping
   between variable names available to the template and absolute URIs
   that are used as global identifiers for the semantics and syntax of
   those variables.

   For example, given the following Resource Object:

     "http://example.org/rel/widget":

     "https://example.org/rel/widget": {
       "href-template":
       "hrefTemplate": "/widgets/{widget_id}",
       "href-vars":
       "hrefVars": {
         "widget_id": "http://example.org/param/widget" "https://example.org/param/widget"
       },
       "hints": {
         "allow": ["GET", "PUT", "DELETE", "PATCH"],
         "formats": {
           "application/json": {}
         },
         "accept-patch":
         "acceptPatch": ["application/json-patch+json"],
         "accept-post": ["application/xml"],
         "accept-ranges":
         "acceptRanges": ["bytes"]
       }
     }

   If you understand that "http://example.org/param/widget" "https://example.org/param/widget" is an
   numeric identifier for a widget, you can then find the resource
   corresponding to widget number 12345 at "http://example.org/ "https://example.org/
   widgets/12345" (assuming that the Home Document is located at
   "http://example.org/").

4.
   "https://example.org/").

5.  Resource Hints

   Resource hints allow clients to find relevant information about
   interacting with a resource beforehand, as a means of optimizing
   communications, as well as advertising available behaviors (e.g., to
   aid in laying out a user interface for consuming the API).

   Hints are just that - they are not a "contract", and are to only be
   taken as advisory.  The runtime behavior of the resource always
   overrides hinted information.

   For example, a resource might hint that the PUT method is allowed on
   all "widget" resources.  This means that generally, the user has the
   ability to PUT to a particular resource, but a specific resource
   might reject a PUT based upon access control or other considerations.
   More fine-grained information might be gathered by interacting with
   the resource (e.g., via a GET), or by another resource "containing"
   it (such as a "widgets" collection) or describing it (e.g., one
   linked to it with a "describedby" "describedBy" link relation).

   This specification defines a set of common hints, based upon
   information that's discoverable by directly interacting with
   resources.  See Section 9.1 7.1 for information on defining new hints.

4.1.

5.1.  allow

   o  Resource Hint Name: allow

   o  Description: Hints the HTTP methods that the current client will
      be able to use to interact with the resource; equivalent to the
      Allow HTTP response header.

   o  Specification: [this document]

   Content MUST be an array of strings, containing HTTP methods.

4.2.

5.2.  formats

   o  Resource Hint Name: formats

   o  Description: Hints the representation types that the resource
      produces and consumes, using the GET and PUT methods respectively,
      subject to the 'allow' hint.

   o  Specification: [this document]

   Content MUST be an object, whose keys are media types, and values are
   objects containing Representation Hints (see Section 5).

4.3.  accept-patch
   objects, currently empty.

5.3.  acceptPatch

   o  Resource Hint Name: accept-patch accept-Patch

   o  Description: Hints the PATCH [RFC5789] request formats accepted by
      the resource for this client; equivalent to the Accept-Patch HTTP
      response header.

   o  Specification: [this document]

   Content MUST be an array of strings, containing media types.

   When this hint is present, "PATCH" SHOULD be listed in the "allow"
   hint.

4.4.  accept-post

5.4.  acceptPost

   o  Resource Hint Name: accept-post acceptPost

   o  Description: Hints the POST request formats accepted by the
      resource for this client.

   o  Specification: [this document]
   Content MUST be an array of strings, containing media types.

   When this hint is present, "POST" SHOULD be listed in the "allow"
   hint.

4.5.  accept-ranges

5.5.  acceptRanges

   o  Resource Hint Name: accept-ranges acceptRanges

   o  Description: Hints the range-specifiers available to the client
      for this resource; equivalent to the Accept-Ranges HTTP response
      header [RFC7233].

   o  Specification: [this document]

   Content MUST be an array of strings, containing HTTP range-
   specifiers.

4.6.  accept-prefer range-specifiers
   (typically, "bytes").

5.6.  acceptPrefer

   o  Resource Hint Name: accept-prefer acceptPrefer

   o  Description: Hints the preferences [RFC7240] supported by the
      resource.  Note that, as per that specifications, a preference can
      be ignored by the server.

   o  Specification: [this document]

   Content MUST be an array of strings, contain containing preferences.

4.7.

5.7.  docs

   o  Resource Hint Name: docs

   o  Description: Hints the location for human-readable documentation
      for the relation type of the resource.

   o  Specification: [this document]

   Content MUST be a string containing an absolute-URI [RFC3986]
   referring to documentation that SHOULD be in HTML format.

4.8.  precondition-req

5.8.  preconditionRequired

   o  Resource Hint Name: precondition-req preconditionRequired
   o  Description: Hints that the resource requires state-changing
      requests (e.g., PUT, PATCH) to include a precondition, as per
      [RFC7232], to avoid conflicts due to concurrent updates.

   o  Specification: [this document]

   Content MUST be an array of strings, with possible values "etag" and
   "last-modified" indicating type of precondition expected.

4.9.  auth-req

5.9.  authSchemes

   o  Resource Hint Name: auth-req authSchemes

   o  Description: Hints that the resource requires authentication using
      the HTTP Authentication Framework [RFC7235].

   o  Specification: [this document]

   Content MUST be an array of objects, each with a "scheme" property
   containing a string that corresponds to a HTTP authentication scheme,
   and optionally a "realms" property containing an array of zero to
   many strings that identify protection spaces that the resource is a
   member of.

   For example, a Resource Object might contain the following hint:

     {
       "auth-req":
       "authSchemes": [
         {
           "scheme": "Basic",
           "realms": ["private"]
         }
       ]
     }

4.10.

5.10.  status

   o  Resource Hint Name: status

   o  Description: Hints the status of the resource.

   o  Specification: [this document]

   Content MUST be a string; possible values are:

   o  "deprecated" - indicates that use of the resource is not
      recommended, but it is still available.

   o  "gone" - indicates that the resource is no longer available; i.e.,
      it will return a 404 (Not Found) or 410 Gone (Gone) HTTP status code if
      accessed.

5.  Representation Hints

   TBD

6.  Creating and Serving Home Documents

   When making a home document available, there are a few things to keep
   in mind:

   o  A home document is best located at a memorable URI, because its
      URI will effectively become the URI for the API itself to clients.

   o  Home documents can be personalized, just as "normal" home pages
      can.  For example, you might advertise different URIs, and/or
      different kinds of link relations, depending on the client's
      identity.

   o  Home documents SHOULD be assigned a freshness lifetime (e.g.,
      "Cache-Control: max-age=3600") so that clients can cache them, to
      avoid having to fetch it every time the client interacts with the
      service.

   o  Custom link relation types, as well as the URIs for variables,
      should lead to documentation for those constructs.

6.1.  Managing Change in Home Documents

   The URIs used in home documents MAY change over time.  However,
   changing them can cause issues for clients that are relying on cached
   home documents containing old links.

   To mitigate the impact of such changes, servers SHOULD consider:

   o  Reducing the freshness lifetime of home documents before a link
      change, so that clients are less likely to refer to an "old"
      document.

   o  Regarding the "old" and "new" URIs as equally valid references for
      an "overlap" period.

   o  After that period, handling requests for the "old" URIs
      appropriately; e.g., with a 404 Not Found, or by redirecting the
      client to the new URI.

6.2.  Evolving and Mixing APIs with Home Documents

   Using home documents affords the opportunity to change the "shape" of
   the API over time, without breaking old clients.

   This includes introducing new functions alongside the old ones - by
   adding new link relation types with corresponding resource objects -
   as well as adding new template variables, media types, and so on.

   It's important to realise that a home document can serve more than
   one "API" at a time; by listing all relevant relation types, it can
   effectively "mix" different APIs, allowing clients to work with
   different resources as they see fit.

6.3.  Documenting APIs that use Home Documents

   Another use case for "static" API description formats like WSDL and
   WADL is to generate documentation for the API from them.

   An API that uses the home document format correctly won't have a need
   to do so, provided that the link relation types and media types it
   uses are well-documented already.

7.  Consuming Home Documents

   Clients might use home documents in a variety of ways.

   In the most common case - actually consuming the API - the client
   will scan the Resources Object for the link relation(s) that it is
   interested in, and then to interact with the resource(s) referred to.
   Resource Hints can be used to optimize communication with the client,
   as well as to inform as to the permissible actions (e.g., whether PUT
   is likely to be supported).

   Note that the home document is a "living" document; it does not
   represent a "contract", but rather is expected to be inspected before
   each interaction.  In particular, links from the home document MUST
   NOT be assumed to be valid beyond the freshness lifetime of the home
   document, as per HTTP's caching model [RFC7234].

   As a result, clients SHOULD cache the home document (as per
   [RFC7234]), to avoid fetching it before every interaction (which
   would otherwise be required).

   Likewise, a client encountering a 404 Not Found on a link SHOULD
   obtain a fresh copy of the home document, to assure that it is up-to-
   date.

8.  Security Considerations

   Clients need to exercise care when using hints.  For example, a naive
   client might send credentials to a server that uses the auth-req
   hint, without checking to see if those credentials are appropriate
   for that server.

9.

7.  IANA Considerations

9.1.

7.1.  HTTP Resource Hint Registry

   This specification defines the HTTP Resource Hint Registry.  See
   Section 4 5 for a general description of the function of resource
   hints.

   In particular, resource hints are generic; that is, they are
   potentially applicable to any resource, not specific to one
   application of HTTP, nor to one particular format.  Generally, they
   ought to be information that would otherwise be discoverable by
   interacting with the resource.

   Hint names MUST be composed of the lowercase letters (a-z), digits
   (0-9), underscores ("_") and hyphens ("-"), and MUST begin with a
   lowercase letter.

   Hint content SHOULD be described in terms of JSON [RFC7159]
   constructs.

   New hints are registered using the Expert Review process described in
   [RFC5226] to enforce the criteria above.  Requests for registration
   of new resource hints are to use the following template:

   o  Resource Hint Name: [hint name]

   o  Description: [a short description of the hint's semantics]

   o  Specification: [reference to specification document]

   Initial registrations are enumerated in Section 4.

9.2.  HTTP Representation Hint Registry

   TBD

9.3. 5.

7.2.  Media Type Registration

   TBD

10.

8.  References

10.1.

8.1.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, 10.17487/
              RFC2119, March 1997,
              <http://www.rfc-editor.org/info/rfc2119>.

   [RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
              Resource Identifier (URI): Generic Syntax", STD 66, RFC
              3986, DOI 10.17487/RFC3986, January 2005,
              <http://www.rfc-editor.org/info/rfc3986>.

   [RFC5226]  Narten, T. and H. Alvestrand, "Guidelines for Writing an
              IANA Considerations Section in RFCs", BCP 26, RFC 5226,
              DOI 10.17487/RFC5226, May 2008,
              <http://www.rfc-editor.org/info/rfc5226>.

   [RFC5988]  Nottingham, M., "Web Linking", RFC 5988, DOI 10.17487/RFC5988, 10.17487/
              RFC5988, October 2010,
              <http://www.rfc-editor.org/info/rfc5988>.

   [RFC6570]  Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
              and D. Orchard, "URI Template", RFC 6570, DOI 10.17487/RFC6570, 10.17487/
              RFC6570, March 2012,
              <http://www.rfc-editor.org/info/rfc6570>.

   [RFC7159]  Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
              Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March
              2014, <http://www.rfc-editor.org/info/rfc7159>.

   [RFC7234]  Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
              Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching",
              RFC 7234, DOI 10.17487/RFC7234, June 2014,
              <http://www.rfc-editor.org/info/rfc7234>.

10.2.

8.2.  Informative References

   [MICROFORMATS]
              microformats.org, "Microformats", n.d.,
              <http://microformats.org/>.

   [RFC4151]  Kindberg, T. and S. Hawke, "The 'tag' URI Scheme", RFC
              4151, DOI 10.17487/RFC4151, October 2005,
              <http://www.rfc-editor.org/info/rfc4151>.

   [RFC5789]  Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC
              5789, DOI 10.17487/RFC5789, March 2010,
              <http://www.rfc-editor.org/info/rfc5789>.

   [RFC6838]  Freed, N., Klensin, J., and T. Hansen, "Media Type
              Specifications and Registration Procedures", BCP 13, RFC
              6838, DOI 10.17487/RFC6838, January 2013,
              <http://www.rfc-editor.org/info/rfc6838>.

   [RFC7230]  Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
              Protocol (HTTP/1.1): Message Syntax and Routing", RFC
              7230, DOI 10.17487/RFC7230, June 2014,
              <http://www.rfc-editor.org/info/rfc7230>.

   [RFC7232]  Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
              Protocol (HTTP/1.1): Conditional Requests", RFC 7232, DOI
              10.17487/RFC7232, June 2014,
              <http://www.rfc-editor.org/info/rfc7232>.

   [RFC7233]  Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed.,
              "Hypertext Transfer Protocol (HTTP/1.1): Range Requests",
              RFC 7233, DOI 10.17487/RFC7233, June 2014,
              <http://www.rfc-editor.org/info/rfc7233>.

   [RFC7235]  Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
              Protocol (HTTP/1.1): Authentication", RFC 7235, DOI
              10.17487/RFC7235, June 2014,
              <http://www.rfc-editor.org/info/rfc7235>.

   [RFC7240]  Snell, J., "Prefer Header for HTTP", RFC 7240, DOI
              10.17487/RFC7240, June 2014,
              <http://www.rfc-editor.org/info/rfc7240>.

   [WADL]     Hadley, M. and Sun Microsystems, "Web Application
              Description Language", n.d.,
              <http://www.w3.org/Submission/wadl/>.

Appendix A.  Acknowledgements

   Thanks to Jan Algermissen, Mike Amundsen, Bill Burke, Sven Dietze,
   Graham Klyne, Leif Hedstrom, Joe Hildebrand, Jeni Tennison, Erik
   Wilde and Jorge Williams for their suggestions and feedback.

Appendix B.  Frequently Asked Questions

B.1.  Why not Microformats?

   Browser-centric Web applications use HTML  Considerations for Creating and Serving Home Documents

   When making an API home document available, there are a few things to
   keep in mind:

   o  A home document is best located at a memorable URI, because its
      URI will effectively become the URI for the API itself to clients.

   o  Home documents can be personalized, just as their representation
   format "normal" home pages
      can.  For example, you might advertise different URIs, and/or
      different kinds of choice.  While link relations, depending on the client's
      identity.

   o  Home documents ought to be assigned a freshness lifetime (e.g.,
      "Cache-Control: max-age=3600") so that clients can cache them, to
      avoid having to fetch it is possible every time the client interacts with the
      service.

   o  Custom link relation types, as well as the URIs for variables,
      should lead to augment HTML documentation for non-
   browser clients (using techniques like Microformats [MICROFORMATS]),
   a few those constructs.

B.1.  Managing Change in Home Documents

   The URIs used in API home documents MAY change over time.  However,
   changing them can cause issues become evident when doing so: for clients that are relying on cached
   home documents containing old links.

   To mitigate the impact of such changes, servers ought to consider:

   o  HTML has  Reducing the freshness lifetime of home documents before a very forgiving syntax.  While this is appropriate for
      browsers (especially considering link
      change, so that there clients are many million HTML
      authors in less likely to refer to an "old"
      document.

   o  Regarding the world), it makes "old" and "new" URIs as equally valid references for
      an "overlap" period.

   o  After that period, handling requests for the "old" URIs
      appropriately; e.g., with a 404 Not Found, or by redirecting the
      client to the new URI.

B.2.  Evolving and Mixing APIs with Home Documents

   Using home documents affords the opportunity to change the "shape" of
   the API over time, without breaking old clients.

   This includes introducing new functions alongside the old ones - by
   adding new link relation types with corresponding resource objects -
   as well as adding new template variables, media types, and so on.

   It's important to realise that a less-than-precise language home document can serve more than
   one "API" at a time; by listing all relevant relation types, it can
   effectively "mix" different APIs, allowing clients to work with
   different resources as they see fit.

Appendix C.  Considerations for machines, resulting Consuming Home Documents

   Clients might use home documents in both overhead (parsing a variety of ways.

   In the most common case - actually consuming the API - the client
   will scan the Resources Object for the link relation(s) that it is
   interested in, and
      transmission) then to interact with the resource(s) referred to.
   Resource Hints can be used to optimize communication with the client,
   as well as lack of precision.

   o  HTML to inform as to the permissible actions (e.g., whether PUT
   is presentation-centric, making it tempting likely to reformat be supported).

   Note that the home document is a "living" document; it
      from time does not
   represent a "contract", but rather is expected to time, be inspected before
   each interaction.  In particular, links from the home document MUST
   NOT be assumed to improve be valid beyond the "look and feel" freshness lifetime of the home
   document, as per HTTP's caching model [RFC7234].

   As a page.
      However, doing so can cause comparatively brittle non-browser result, clients ought to lose their understanding of cache the content's semantics,
      unless very careful controls are in place.

   Because of this, it's most practical home document (as per
   [RFC7234]), to define avoid fetching it before every interaction (which
   would otherwise be required).

   Likewise, a separate format, and
   JSON client encountering a 404 Not Found on a link is easily machine-readable, precise, and has
   encouraged obtain a better chance fresh copy of
   being managed for stability.

B.2. the home document, to assure that
   it is up-to-date.

Appendix D.  Frequently Asked Questions

D.1.  Why doesn't the format allow references or inheritance?

   Adding inheritance or references would allow more modularity in the
   format and make it more compact, at the cost of considerable
   complexity and the associated potential for errors (both in the
   specification and by its users).

   Since good tools and compression are effective ways to achieve the
   same ends, this specification doesn't attempt them.

B.3.  What about authentication?

   In HTTP, authentication is discoverable by interacting with the
   resource (usually, by getting a 401 Unauthorized response status
   code, along with one or more challenges).  While the home document
   could hint it, this isn't yet done, to avoid possible security
   complications.

B.4.

D.2.  What about "Faults" (i.e., errors)?

   In HTTP, errors are conveyed by HTTP status codes.  While this
   specification could (and even may) allow enumeration of possible
   error conditions, there's a concern that this will encourage
   applications to define many such "faults", leading to tight coupling
   between the application and its clients.

B.5.

D.3.  How Do I find the schema for a format?

   That isn't addressed by home documents.  Ultimately, it's up to the
   media type accepted and generated by resources to define and
   constrain (or not) their syntax.

B.6.

D.4.  How do I express complex query arguments?

   Complex queries - i.e., those that exceed the expressive power of
   Link Templates or would require ambiguous properties of a "resources"
   object - aren't intended to be defined by a home document.  The
   appropriate way to do this is with a "form" language, much as HTML
   defines.

   Note that it is possible to support multiple query syntaxes on the
   same base URL, using more than one link relation type; see the
   example at the start of the document.

Appendix C.  Open Issues

   The following is a list of placeholders for open issues.

   o  top-level object(s)

      *  contact details

      *  overall documentation

      *  release info?

      *  ToS

      *  rate limiting (per-resource?)

   o  Resource Hints

      *  indicate a POST to 201 Created pattern

      *  indicate an "action" POST

      *  outbound links

      *  forms?

   o  Representation Hints
      *  format profiles

      *  deprecation

   o  Defining new top-level and resource object properties - how new
      ones are minted, registry, etc.

   o  Discovery (e.g., conneg, .well-known, etc.)

   o  LIMITED include function?

Author's Address

   Mark Nottingham

   Email: mnot@mnot.net
   URI:   http://www.mnot.net/   https://www.mnot.net/