<?xml version="1.0" encoding="UTF-8"?>
  <?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?>
  <!-- generated by https://github.com/cabo/kramdown-rfc2629 version 1.0.40 -->

<!DOCTYPE rfc SYSTEM "../Tools/rfc2629xslt/rfc2629.dtd" [
]>

<?rfc toc="yes"?>
<?rfc tocindent="yes"?>
<?rfc sortrefs="yes"?>
<?rfc symrefs="yes"?>
<?rfc strict="yes"?>
<?rfc compact="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>

<rfc ipr="trust200902" docName="draft-nottingham-json-home-06" category="info">

  <front>
    <title>Home Documents for HTTP APIs</title>

    <author initials="M." surname="Nottingham" fullname="Mark Nottingham">
      <organization></organization>
      <address>
        <email>mnot@mnot.net</email>
        <uri>https://www.mnot.net/</uri>
      </address>
    </author>

    <date year="2017"/>

    <area>General</area>
    
    <keyword>Internet-Draft</keyword>

    <abstract>


<t>This document proposes a “home document” format for non-browser HTTP clients.</t>



    </abstract>


    <note title="Note to Readers">


<t>The issues list for this draft can be found at <eref target="https://github.com/mnot/I-D/labels/json-home">https://github.com/mnot/I-D/labels/json-home</eref>.</t>

<t>The most recent (often, unpublished) draft is at <eref target="https://mnot.github.io/I-D/json-home/">https://mnot.github.io/I-D/json-home/</eref>.</t>

<t>Recent changes are listed at <eref target="https://github.com/mnot/I-D/commits/gh-pages/json-home">https://github.com/mnot/I-D/commits/gh-pages/json-home</eref>.</t>

<t>For information about implementations, see <eref target="https://github.com/mnot/I-D/wiki/json-home">https://github.com/mnot/I-D/wiki/json-home</eref>.</t>


    </note>


  </front>

  <middle>


<section anchor="introduction" title="Introduction">

<t>It is becoming increasingly common to use HTTP <xref target="RFC7230"/> for applications other than traditional
Web browsing. Such “HTTP APIs” are used to integrate processes on disparate systems, make
information available to machines across the Internet, and as part of the implementation of
“micro-services.”</t>

<t>By using HTTP, these applications realise a number of benefits, from message framing to caching,
and well-defined semantics that are broadly understood and useful.</t>

<t>Often, these applications of HTTP are defined by documenting static URLs that clients need to 
know and servers need to implement. Any interaction outside of these bounds is uncharted territory.</t>

<t>For some applications, this approach brings issues, especially when the interface changes, either
due to evolution, extension or drift between implementations. Furthermore, implementing more than
one instance of interface can bring further issues, as different environments have different
requirements.</t>

<t>The Web itself offers one way to address these issues, using links <xref target="RFC3986"/> to navigate between
states. A link-driven application discovers relevant resources at run time, using a shared
vocabulary of link relations <xref target="RFC5988"/> and internet media types <xref target="RFC6838"/> to support a “follow
your nose” style of interaction – just as a Web browser does to navigate the Web.</t>

<t>A client can then decide 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.</t>

<t>Doing so can provide any of a number of benefits, including:</t>

<t><list style="symbols">
  <t>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.</t>
  <t>Evolvability - Likewise, interfaces can change gradually by introducing a new link relation and/or format while still supporting the old ones.</t>
  <t>Customisation - Home documents can be tailored for the client, allowing diffrent classes of service or different client permissions to be exposed naturally.</t>
  <t>Flexible deployment - Since URLs aren’t baked into documentation, the server can choose what URLs to use for a given service.</t>
  <t>API mixing - Likewise, more than one API can be deployed on a given server, without fear of collisions.</t>
</list></t>

<t>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.</t>

<t>This document defines a “home page” format using the JSON format <xref target="RFC7159"/> for APIs to use as a
launching point for the interactions they offer, using links. Having a well-defined format for this
purpose promotes good practice and tooling.</t>

<section anchor="notational-conventions" title="Notational Conventions">

<t>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
<xref target="RFC2119"/>.</t>

</section>
</section>
<section anchor="api-home-documents" title="API Home Documents">

<t>An API Home Document (or, interchangeably, “home document”) uses the format described in <xref target="RFC7159"/>
and has the media type “application/json-home”.</t>

<t><spanx style="strong">Note: this media type is not final, and will change before final publication.</spanx></t>

<t>Its content consists of a root object with:</t>

<t><list style="symbols">
  <t>A “resources” member, whose value is an object that describes the resources associated with the
API. Its member names are link relation types (as defined by <xref target="RFC5988"/>), and their values are
Resource Objects (<xref target="resource-object"/>).</t>
  <t>Optionally, a “api” member, whose value is an API Object (<xref target="api-object"/>) that contains
information about the API as a whole.</t>
</list></t>

<t>For example:</t>

<figure><artwork><![CDATA[
  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": {
        "hrefTemplate": "/widgets/{widget_id}",
        "hrefVars": {
          "widget_id": "https://example.org/param/widget"
        },
        "hints": {
          "allow": ["GET", "PUT", "DELETE", "PATCH"],
          "formats": {
            "application/json": {}
          },
          "acceptPatch": ["application/json-patch+json"],
          "acceptRanges": ["bytes"]
        }
      }
    }
  }
]]></artwork></figure>

<t>Here, we have a home document 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/”.</t>

<t>It links to a 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 <xref target="RFC6570"/>, along with a mapping of identifiers to a variable for use in that
template.</t>

<t>It also gives several hints about interacting with the latter “widget” resources, including the
HTTP methods usable with them, the PATCH and POST formats they accept, and the fact that they
support partial requests <xref target="RFC7233"/> using the “bytes” range-specifier.</t>

<t>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.</t>

<t>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.:</t>

<figure><artwork><![CDATA[
{
  "resources": {
    "tag:me@example.com,2016:search-by-id": {
      "hrefTemplate": "/search?id={widget_id}",
      "hrefVars": {
        "widget_id": "https://example.org/param/widget_id"
      }
    },
    "tag:me@example.com,2016:search-by-name": {
      "hrefTemplate": "/search?name={widget_name}",
      "hrefVars": {
        "widget_name": "https://example.org/param/widget_name"
      }
    }
  }
}
]]></artwork></figure>

<t>Note that the examples above use both tag <xref target="RFC4151"/> and https <xref target="RFC7230"/> URIs; any URI scheme
can be used to identify link relations and other artefacts in home documents. Typically, these are
not links to be followed; they are only used to identify things.</t>

</section>
<section anchor="api-object" title="API Objects">

<t>An API Object contains links to information about the API itself.</t>

<t>Two optional members are defined:</t>

<t><list style="symbols">
  <t>“title” has a string value indicating the name of the API;</t>
  <t>“links” has an object value, whose member names are link relation types <xref target="RFC5988"/>, and values
are URLs <xref target="RFC3986"/>. The context of these links is the API home document as a whole.</t>
</list></t>

<t>No links are required to be conveyed, but APIs might benefit from setting the following:</t>

<t><list style="symbols">
  <t>author - a suitable URL (e.g., mailto: or https:) for the author(s) of the API</t>
  <t>describedBy - a link to documentation for the API</t>
  <t>license - a link to the legal terms for using the API</t>
</list></t>

<t>Future members of the API Object MAY be defined by specifications that update this document.</t>

</section>
<section anchor="resource-object" title="Resource Objects">

<t>A Resource Object links to resources of the type indicated in their name 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.</t>

<t>Direct links are indicated with an “href” property, whose value is a URI <xref target="RFC3986"/>.</t>

<t>Templated links are indicated with an “hrefTemplate” property, whose value is a URI Template
<xref target="RFC6570"/>. When “hrefTemplate” is present, the Resource Object MUST have a “hrefVars” property;
see “Resolving Templated Links”.</t>

<t>Resource Objects MUST have exactly one of the “href” or “href-vars” properties.</t>

<t>In both forms, the links that “href” and “hrefTemplate” refer to are URI-references <xref target="RFC3986"/>
whose base URI is that of the API Home Document itself.</t>

<t>Resource Objects MAY also have a “hints” property, whose value is an object that uses named
Resource Hints (see <xref target="resource_hints"/>) as its properties.</t>

<section anchor="resolving-templated-links" title="Resolving Templated Links">

<t>A URI can be derived from a Templated Link by treating the “hrefTemplate” value as a Level 3 URI
Template <xref target="RFC6570"/>, using the “hrefVars” property to fill the template.</t>

<t>The “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.</t>

<t>For example, given the following Resource Object:</t>

<figure><artwork><![CDATA[
  "https://example.org/rel/widget": {
    "hrefTemplate": "/widgets/{widget_id}",
    "hrefVars": {
      "widget_id": "https://example.org/param/widget"
    },
    "hints": {
      "allow": ["GET", "PUT", "DELETE", "PATCH"],
      "formats": {
        "application/json": {}
      },
      "acceptPatch": ["application/json-patch+json"],
      "acceptRanges": ["bytes"]
    }
  }
]]></artwork></figure>

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

</section>
</section>
<section anchor="resource_hints" title="Resource Hints">

<t>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).</t>

<t>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.</t>

<t>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” link relation).</t>

<t>This specification defines a set of common hints, based upon information that’s discoverable by
directly interacting with resources. See <xref target="resource_hint_registry"/> for information on defining new
hints.</t>

<section anchor="allow" title="allow">

<t><list style="symbols">
  <t>Resource Hint Name: allow</t>
  <t>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.</t>
  <t>Specification: [this document]</t>
</list></t>

<t>Content MUST be an array of strings, containing HTTP methods. As per HTTP, when GET is supported, a
client MAY assume that HEAD is supported.</t>

</section>
<section anchor="formats" title="formats">

<t><list style="symbols">
  <t>Resource Hint Name: formats</t>
  <t>Description: Hints the representation types that the resource makes available, using the
GET method.</t>
  <t>Specification: [this document]</t>
</list></t>

<t>Content MUST be an object, whose keys are media types, and values are objects, currently empty.</t>

</section>
<section anchor="acceptpatch" title="acceptPatch">

<t><list style="symbols">
  <t>Resource Hint Name: accept-Patch</t>
  <t>Description: Hints the PATCH <xref target="RFC5789"/> request formats accepted by the resource for this
client; equivalent to the Accept-Patch HTTP response header.</t>
  <t>Specification: [this document]</t>
</list></t>

<t>Content MUST be an array of strings, containing media types.</t>

<t>When this hint is present, “PATCH” SHOULD be listed in the “allow” hint.</t>

</section>
<section anchor="acceptpost" title="acceptPost">

<t><list style="symbols">
  <t>Resource Hint Name: acceptPost</t>
  <t>Description: Hints the POST request formats accepted by the resource for this client.</t>
  <t>Specification: [this document]</t>
</list></t>

<t>Content MUST be an array of strings, containing media types.</t>

<t>When this hint is present, “POST” SHOULD be listed in the “allow” hint.</t>

</section>
<section anchor="acceptput" title="acceptPut">

<t><list style="symbols">
  <t>Resource Hint Name: acceptPut</t>
  <t>Description: Hints the PUT request formats accepted by the resource for this client.</t>
  <t>Specification: [this document]</t>
</list></t>

<t>Content MUST be an array of strings, containing media types.</t>

<t>When this hint is present, “PUT” SHOULD be listed in the “allow” hint.</t>

</section>
<section anchor="acceptranges" title="acceptRanges">

<t><list style="symbols">
  <t>Resource Hint Name: acceptRanges</t>
  <t>Description: Hints the range-specifiers available to the client for this resource; equivalent to
the Accept-Ranges HTTP response header <xref target="RFC7233"/>.</t>
  <t>Specification: [this document]</t>
</list></t>

<t>Content MUST be an array of strings, containing HTTP range-specifiers (typically, “bytes”).</t>

</section>
<section anchor="acceptprefer" title="acceptPrefer">

<t><list style="symbols">
  <t>Resource Hint Name: acceptPrefer</t>
  <t>Description: Hints the preferences <xref target="RFC7240"/> supported by the resource. Note that, as per that
specifications, a preference can be ignored by the server.</t>
  <t>Specification: [this document]</t>
</list></t>

<t>Content MUST be an array of strings, containing preferences.</t>

</section>
<section anchor="docs" title="docs">

<t><list style="symbols">
  <t>Resource Hint Name: docs</t>
  <t>Description: Hints the location for human-readable documentation for the relation type of the
resource.</t>
  <t>Specification: [this document]</t>
</list></t>

<t>Content MUST be a string containing an absolute-URI <xref target="RFC3986"/> referring to documentation that
SHOULD be in HTML format.</t>

</section>
<section anchor="preconditionrequired" title="preconditionRequired">

<t><list style="symbols">
  <t>Resource Hint Name: preconditionRequired</t>
  <t>Description: Hints that the resource requires state-changing requests (e.g., PUT, PATCH) to
include a precondition, as per <xref target="RFC7232"/>, to avoid conflicts due to concurrent updates.</t>
  <t>Specification: [this document]</t>
</list></t>

<t>Content MUST be an array of strings, with possible values “etag” and “last-modified” indicating
type of precondition expected.</t>

</section>
<section anchor="authschemes" title="authSchemes">

<t><list style="symbols">
  <t>Resource Hint Name: authSchemes</t>
  <t>Description: Hints that the resource requires authentication using the HTTP Authentication
Framework <xref target="RFC7235"/>.</t>
  <t>Specification: [this document]</t>
</list></t>

<t>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.</t>

<t>For example, a Resource Object might contain the following hint:</t>

<figure><artwork><![CDATA[
  {
    "authSchemes": [
      {
        "scheme": "Basic",
        "realms": ["private"]
      }
    ]
  }
]]></artwork></figure>

</section>
<section anchor="status" title="status">

<t><list style="symbols">
  <t>Resource Hint Name: status</t>
  <t>Description: Hints the status of the resource.</t>
  <t>Specification: [this document]</t>
</list></t>

<t>Content MUST be a string; possible values are:</t>

<t><list style="symbols">
  <t>“deprecated” - indicates that use of the resource is not recommended, but it is still available.</t>
  <t>“gone” - indicates that the resource is no longer available; i.e., it will return a 404 (Not
Found) or 410 (Gone) HTTP status code if accessed.</t>
</list></t>

</section>
</section>
<section anchor="security-considerations" title="Security Considerations">

<t>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.</t>

</section>
<section anchor="iana-considerations" title="IANA Considerations">

<section anchor="resource_hint_registry" title="HTTP Resource Hint Registry">

<t>This specification defines the HTTP Resource Hint Registry. See <xref target="resource_hints"/> for a general
description of the function of resource hints.</t>

<t>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.</t>

<t>Hint names MUST be composed of the lowercase letters (a-z), digits (0-9), underscores (“_”) and
hyphens (“-“), and MUST begin with a lowercase letter.</t>

<t>Hint content SHOULD be described in terms of JSON <xref target="RFC7159"/> constructs.</t>

<t>New hints are registered using the Expert Review process described in <xref target="RFC5226"/> to enforce the
criteria above. Requests for registration of new resource hints are to use the following template:</t>

<t><list style="symbols">
  <t>Resource Hint Name: [hint name]</t>
  <t>Description: [a short description of the hint’s semantics]</t>
  <t>Specification: [reference to specification document]</t>
</list></t>

<t>Initial registrations are enumerated in <xref target="resource_hints"/>.</t>

</section>
<section anchor="media-type-registration" title="Media Type Registration">

<t>TBD</t>

</section>
</section>


  </middle>

  <back>

    <references title='Normative References'>





<reference  anchor='RFC2119' target='http://www.rfc-editor.org/info/rfc2119'>
<front>
<title>Key words for use in RFCs to Indicate Requirement Levels</title>
<author initials='S.' surname='Bradner' fullname='S. Bradner'><organization /></author>
<date year='1997' month='March' />
<abstract><t>In many standards track documents several words are used to signify the requirements in the specification.  These words are often capitalized. This document defines these words as they should be interpreted in IETF documents.  This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.</t></abstract>
</front>
<seriesInfo name='BCP' value='14'/>
<seriesInfo name='RFC' value='2119'/>
<seriesInfo name='DOI' value='10.17487/RFC2119'/>
</reference>



<reference  anchor='RFC3986' target='http://www.rfc-editor.org/info/rfc3986'>
<front>
<title>Uniform Resource Identifier (URI): Generic Syntax</title>
<author initials='T.' surname='Berners-Lee' fullname='T. Berners-Lee'><organization /></author>
<author initials='R.' surname='Fielding' fullname='R. Fielding'><organization /></author>
<author initials='L.' surname='Masinter' fullname='L. Masinter'><organization /></author>
<date year='2005' month='January' />
<abstract><t>A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource.  This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet.  The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier.  This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme.  [STANDARDS-TRACK]</t></abstract>
</front>
<seriesInfo name='STD' value='66'/>
<seriesInfo name='RFC' value='3986'/>
<seriesInfo name='DOI' value='10.17487/RFC3986'/>
</reference>



<reference  anchor='RFC5226' target='http://www.rfc-editor.org/info/rfc5226'>
<front>
<title>Guidelines for Writing an IANA Considerations Section in RFCs</title>
<author initials='T.' surname='Narten' fullname='T. Narten'><organization /></author>
<author initials='H.' surname='Alvestrand' fullname='H. Alvestrand'><organization /></author>
<date year='2008' month='May' />
<abstract><t>Many protocols make use of identifiers consisting of constants and other well-known values.  Even after a protocol has been defined and deployment has begun, new values may need to be assigned (e.g., for a new option type in DHCP, or a new encryption or authentication transform for IPsec).  To ensure that such quantities have consistent values and interpretations across all implementations, their assignment must be administered by a central authority.  For IETF protocols, that role is provided by the Internet Assigned Numbers Authority (IANA).</t><t>In order for IANA to manage a given namespace prudently, it needs guidelines describing the conditions under which new values can be assigned or when modifications to existing values can be made.  If IANA is expected to play a role in the management of a namespace, IANA must be given clear and concise instructions describing that role.  This document discusses issues that should be considered in formulating a policy for assigning values to a namespace and provides guidelines for authors on the specific text that must be included in documents that place demands on IANA.</t><t>This document obsoletes RFC 2434.  This document specifies an Internet Best  Current Practices for the Internet Community, and requests discussion and  suggestions for improvements.</t></abstract>
</front>
<seriesInfo name='BCP' value='26'/>
<seriesInfo name='RFC' value='5226'/>
<seriesInfo name='DOI' value='10.17487/RFC5226'/>
</reference>



<reference  anchor='RFC5988' target='http://www.rfc-editor.org/info/rfc5988'>
<front>
<title>Web Linking</title>
<author initials='M.' surname='Nottingham' fullname='M. Nottingham'><organization /></author>
<date year='2010' month='October' />
<abstract><t>This document specifies relation types for Web links, and defines a registry for them.  It also defines the use of such links in HTTP headers with the Link header field.  [STANDARDS-TRACK]</t></abstract>
</front>
<seriesInfo name='RFC' value='5988'/>
<seriesInfo name='DOI' value='10.17487/RFC5988'/>
</reference>



<reference  anchor='RFC6570' target='http://www.rfc-editor.org/info/rfc6570'>
<front>
<title>URI Template</title>
<author initials='J.' surname='Gregorio' fullname='J. Gregorio'><organization /></author>
<author initials='R.' surname='Fielding' fullname='R. Fielding'><organization /></author>
<author initials='M.' surname='Hadley' fullname='M. Hadley'><organization /></author>
<author initials='M.' surname='Nottingham' fullname='M. Nottingham'><organization /></author>
<author initials='D.' surname='Orchard' fullname='D. Orchard'><organization /></author>
<date year='2012' month='March' />
<abstract><t>A URI Template is a compact sequence of characters for describing a range of Uniform Resource Identifiers through variable expansion. This specification defines the URI Template syntax and the process for expanding a URI Template into a URI reference, along with guidelines for the use of URI Templates on the Internet.   [STANDARDS-TRACK]</t></abstract>
</front>
<seriesInfo name='RFC' value='6570'/>
<seriesInfo name='DOI' value='10.17487/RFC6570'/>
</reference>



<reference  anchor='RFC7159' target='http://www.rfc-editor.org/info/rfc7159'>
<front>
<title>The JavaScript Object Notation (JSON) Data Interchange Format</title>
<author initials='T.' surname='Bray' fullname='T. Bray' role='editor'><organization /></author>
<date year='2014' month='March' />
<abstract><t>JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format.  It was derived from the ECMAScript Programming Language Standard.  JSON defines a small set of formatting rules for the portable representation of structured data.</t><t>This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance.</t></abstract>
</front>
<seriesInfo name='RFC' value='7159'/>
<seriesInfo name='DOI' value='10.17487/RFC7159'/>
</reference>



<reference  anchor='RFC7234' target='http://www.rfc-editor.org/info/rfc7234'>
<front>
<title>Hypertext Transfer Protocol (HTTP/1.1): Caching</title>
<author initials='R.' surname='Fielding' fullname='R. Fielding' role='editor'><organization /></author>
<author initials='M.' surname='Nottingham' fullname='M. Nottingham' role='editor'><organization /></author>
<author initials='J.' surname='Reschke' fullname='J. Reschke' role='editor'><organization /></author>
<date year='2014' month='June' />
<abstract><t>The Hypertext Transfer Protocol (HTTP) is a stateless \%application- level protocol for distributed, collaborative, hypertext information systems.  This document defines HTTP caches and the associated header fields that control cache behavior or indicate cacheable response messages.</t></abstract>
</front>
<seriesInfo name='RFC' value='7234'/>
<seriesInfo name='DOI' value='10.17487/RFC7234'/>
</reference>




    </references>

    <references title='Informative References'>





<reference  anchor='RFC5789' target='http://www.rfc-editor.org/info/rfc5789'>
<front>
<title>PATCH Method for HTTP</title>
<author initials='L.' surname='Dusseault' fullname='L. Dusseault'><organization /></author>
<author initials='J.' surname='Snell' fullname='J. Snell'><organization /></author>
<date year='2010' month='March' />
<abstract><t>Several applications extending the Hypertext Transfer Protocol (HTTP) require a feature to do partial resource modification.  The existing HTTP PUT method only allows a complete replacement of a document. This proposal adds a new HTTP method, PATCH, to modify an existing HTTP resource.  [STANDARDS-TRACK]</t></abstract>
</front>
<seriesInfo name='RFC' value='5789'/>
<seriesInfo name='DOI' value='10.17487/RFC5789'/>
</reference>



<reference  anchor='RFC6838' target='http://www.rfc-editor.org/info/rfc6838'>
<front>
<title>Media Type Specifications and Registration Procedures</title>
<author initials='N.' surname='Freed' fullname='N. Freed'><organization /></author>
<author initials='J.' surname='Klensin' fullname='J. Klensin'><organization /></author>
<author initials='T.' surname='Hansen' fullname='T. Hansen'><organization /></author>
<date year='2013' month='January' />
<abstract><t>This document defines procedures for the specification and registration of media types for use in HTTP, MIME, and other Internet protocols.  This memo documents an Internet Best Current Practice.</t></abstract>
</front>
<seriesInfo name='BCP' value='13'/>
<seriesInfo name='RFC' value='6838'/>
<seriesInfo name='DOI' value='10.17487/RFC6838'/>
</reference>



<reference  anchor='RFC7232' target='http://www.rfc-editor.org/info/rfc7232'>
<front>
<title>Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests</title>
<author initials='R.' surname='Fielding' fullname='R. Fielding' role='editor'><organization /></author>
<author initials='J.' surname='Reschke' fullname='J. Reschke' role='editor'><organization /></author>
<date year='2014' month='June' />
<abstract><t>The Hypertext Transfer Protocol (HTTP) is a stateless application- level protocol for distributed, collaborative, hypertext information systems.  This document defines HTTP/1.1 conditional requests, including metadata header fields for indicating state changes, request header fields for making preconditions on such state, and rules for constructing the responses to a conditional request when one or more preconditions evaluate to false.</t></abstract>
</front>
<seriesInfo name='RFC' value='7232'/>
<seriesInfo name='DOI' value='10.17487/RFC7232'/>
</reference>



<reference  anchor='RFC7233' target='http://www.rfc-editor.org/info/rfc7233'>
<front>
<title>Hypertext Transfer Protocol (HTTP/1.1): Range Requests</title>
<author initials='R.' surname='Fielding' fullname='R. Fielding' role='editor'><organization /></author>
<author initials='Y.' surname='Lafon' fullname='Y. Lafon' role='editor'><organization /></author>
<author initials='J.' surname='Reschke' fullname='J. Reschke' role='editor'><organization /></author>
<date year='2014' month='June' />
<abstract><t>The Hypertext Transfer Protocol (HTTP) is a stateless application- level protocol for distributed, collaborative, hypertext information systems.  This document defines range requests and the rules for constructing and combining responses to those requests.</t></abstract>
</front>
<seriesInfo name='RFC' value='7233'/>
<seriesInfo name='DOI' value='10.17487/RFC7233'/>
</reference>



<reference  anchor='RFC7235' target='http://www.rfc-editor.org/info/rfc7235'>
<front>
<title>Hypertext Transfer Protocol (HTTP/1.1): Authentication</title>
<author initials='R.' surname='Fielding' fullname='R. Fielding' role='editor'><organization /></author>
<author initials='J.' surname='Reschke' fullname='J. Reschke' role='editor'><organization /></author>
<date year='2014' month='June' />
<abstract><t>The Hypertext Transfer Protocol (HTTP) is a stateless application- level protocol for distributed, collaborative, hypermedia information systems.  This document defines the HTTP Authentication framework.</t></abstract>
</front>
<seriesInfo name='RFC' value='7235'/>
<seriesInfo name='DOI' value='10.17487/RFC7235'/>
</reference>



<reference  anchor='RFC7240' target='http://www.rfc-editor.org/info/rfc7240'>
<front>
<title>Prefer Header for HTTP</title>
<author initials='J.' surname='Snell' fullname='J. Snell'><organization /></author>
<date year='2014' month='June' />
<abstract><t>This specification defines an HTTP header field that can be used by a client to request that certain behaviors be employed by a server while processing a request.</t></abstract>
</front>
<seriesInfo name='RFC' value='7240'/>
<seriesInfo name='DOI' value='10.17487/RFC7240'/>
</reference>



<reference  anchor='RFC4151' target='http://www.rfc-editor.org/info/rfc4151'>
<front>
<title>The 'tag' URI Scheme</title>
<author initials='T.' surname='Kindberg' fullname='T. Kindberg'><organization /></author>
<author initials='S.' surname='Hawke' fullname='S. Hawke'><organization /></author>
<date year='2005' month='October' />
<abstract><t>This document describes the &quot;tag&quot; Uniform Resource Identifier (URI) scheme.  Tag URIs (also known as &quot;tags&quot;) are designed to be unique across space and time while being tractable to humans.  They are distinct from most other URIs in that they have no authoritative resolution mechanism.  A tag may be used purely as an entity identifier.  Furthermore, using tags has some advantages over the common practice of using &quot;http&quot; URIs as identifiers for non-HTTP-accessible resources.  This memo provides information for the Internet community.</t></abstract>
</front>
<seriesInfo name='RFC' value='4151'/>
<seriesInfo name='DOI' value='10.17487/RFC4151'/>
</reference>



<reference  anchor='RFC7230' target='http://www.rfc-editor.org/info/rfc7230'>
<front>
<title>Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing</title>
<author initials='R.' surname='Fielding' fullname='R. Fielding' role='editor'><organization /></author>
<author initials='J.' surname='Reschke' fullname='J. Reschke' role='editor'><organization /></author>
<date year='2014' month='June' />
<abstract><t>The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems.  This document provides an overview of HTTP architecture and its associated terminology, defines the &quot;http&quot; and &quot;https&quot; Uniform Resource Identifier (URI) schemes, defines the HTTP/1.1 message syntax and parsing requirements, and describes related security concerns for implementations.</t></abstract>
</front>
<seriesInfo name='RFC' value='7230'/>
<seriesInfo name='DOI' value='10.17487/RFC7230'/>
</reference>



<reference  anchor='RFC7807' target='http://www.rfc-editor.org/info/rfc7807'>
<front>
<title>Problem Details for HTTP APIs</title>
<author initials='M.' surname='Nottingham' fullname='M. Nottingham'><organization /></author>
<author initials='E.' surname='Wilde' fullname='E. Wilde'><organization /></author>
<date year='2016' month='March' />
<abstract><t>This document defines a &quot;problem detail&quot; as a way to carry machine- readable details of errors in a HTTP response to avoid the need to define new error response formats for HTTP APIs.</t></abstract>
</front>
<seriesInfo name='RFC' value='7807'/>
<seriesInfo name='DOI' value='10.17487/RFC7807'/>
</reference>




    </references>


<section anchor="acknowledgements" title="Acknowledgements">

<t>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.</t>

</section>
<section anchor="creating-and-serving-home-documents" title="Creating and Serving Home Documents">

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

<t><list style="symbols">
  <t>A home document is best located at a memorable URI, because its URI will effectively become the
URI for the API itself to clients.</t>
  <t>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.</t>
  <t>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 every time the client interacts with the
service.</t>
  <t>Custom link relation types, as well as the URIs for variables, should lead to documentation for
those constructs.</t>
</list></t>

<section anchor="managing-change-in-home-documents" title="Managing Change in Home Documents">

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

<t>To mitigate the impact of such changes, servers ought to consider:</t>

<t><list style="symbols">
  <t>Reducing the freshness lifetime of home documents before a link change, so that clients are less
likely to refer to an “old” document.</t>
  <t>Regarding the “old” and “new” URIs as equally valid references for an “overlap” period.</t>
  <t>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.</t>
</list></t>

</section>
<section anchor="evolving-and-mixing-apis-with-home-documents" title="Evolving and Mixing APIs with Home Documents">

<t>Using home documents affords the opportunity to change the “shape” of the API over time, without
breaking old clients.</t>

<t>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.</t>

<t>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.</t>

</section>
</section>
<section anchor="consuming-home-documents" title="Consuming Home Documents">

<t>Clients might use home documents in a variety of ways.</t>

<t>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).</t>

<t>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 <xref target="RFC7234"/>.</t>

<t>As a result, clients ought to cache the home document (as per <xref target="RFC7234"/>), to avoid fetching it
before every interaction (which would otherwise be required).</t>

<t>Likewise, a client encountering a 404 (Not Found) on a link is encouraged obtain a fresh copy of
the home document, to assure that it is up-to-date.</t>

</section>
<section anchor="frequently-asked-questions" title="Frequently Asked Questions">

<section anchor="why-not-use-insert-other-service-description-format" title="Why not use (insert other service description format)?">

<t>There are a fair number of existing service description formats, including those that specialise in
“RESTful” interactions. However, these formats generally are optimised for pairwise integration, or
one-server-to-many-client integration, and less capable of describing protocols where both the
server and client can evolve and be extended.</t>

</section>
<section anchor="why-doesnt-the-format-allow-references-or-inheritance" title="Why doesn’t the format allow references or inheritance?">

<t>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).</t>

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

</section>
<section anchor="what-about-faults-ie-errors" title="What about “Faults” (i.e., errors)?">

<t>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. See <xref target="RFC7807"/> for further considerations.</t>

</section>
<section anchor="how-do-i-find-the-schema-for-a-format" title="How Do I find the schema for a format?">

<t>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.</t>

</section>
<section anchor="how-do-i-express-complex-query-arguments" title="How do I express complex query arguments?">

<t>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.</t>

<t>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.</t>

</section>
</section>


  </back>

<!-- ##markdown-source:
H4sIAGLfo1gAA9VcWZPbRpJ+x6+ooB/c7SXZrcuSWzvrbeuw2qPDI7XWMeFQ
OECiSGIaBDgooClaofntm19mVqEAsiXbs7Mb6weZTQJ1ZOX5ZWZNJpOkyZvC
npln1dqax9W8XduycWZR1ebZ5eWP5vzHC5eks1ltr8+SrJqX6Zqezup00UzK
qmnycrlK15O/uaqcrGiMyenXSZY29Mzt01v3kzl9XFb17szk5aJKknxTn5mm
bl1z+/T0m9PbSVrb9Mx8b0tbp0WyreqrZV21m7Pkyu7or+zMXJSNrUvbTB5j
0iRxTVpmv6RFVdIkO+uSTX5mfm6q+djQP3mZ0QbGxlV1U9uFo0+7tX5o6nxO
P82r9SbVD7zbMS2uyEv7LknStllV9VliJomh//LSnZkXU/My7JS/FiK8SOur
4S9VvUzL/Ne0yavyjL+x6zQvzsyaiPWf+GdKW+Ef2prWvWqajTs7Odlut1P/
60mSlFW9pjGuLcZ4/fTR7Vu3vtGPd7558LV+vHf7dvj4zYMH+vHre/dP9eP9
W/f8a/dv37l7RvSnU+gPfe/+A//M1w/uPOgev919vNN9vBc+3qVZkslkYtIZ
UZYImiSXq9yZTJnIbOpqUznrTGpGYI3wy8jIIpjLSmKcWV1tnVWOmxc5DmUq
gxNN7C8v8U9T/fLappmtHSayJneupcGL3MlADU8OHjHztDQzS9+2ZWZonn/3
ZF7mzaqdTengT0Dtk4vJ45MindnCnQQO/o+pjL+uaODazrGVo2rR2HJs2nLT
zmjGlc2OdS6aNJ6BD1GnySueIIx8gqFfy4jzVVouQZva8hbs5xcKds0bd7Jc
TTYpvdtf8lMiQTjdqqRTqVpa3XpTWNCcv4QQWPvpWbb5Vd4fGcewzrOssEny
BcSxrrJ2jvGS5IIJMLM0BEkBLWBO8uzoY7Fj8aKFNJVpnZWz/fBBuOj040c+
s3SzKfK5rM1UzcriGOnwiJ+yHN+STvjJzgwzCI06NW/a+cqMgmoaMQFp/Azz
5KQqljWpHPDe3DowH60gy90m5a/djii9JjKs0yub9Mh1TWKazgqLcdbpfEX6
gE5nXlfO0ZpsUENjk4KpnKEhG1Mt+Mc+menbZLTO6d0JcfV1TiuZjpLkux0t
FFTC6sd4j8jSowDRjniBvjRlu54RMWj4GanGRQ4ltairtVnTrujw6Y+UKU6r
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

-->

</rfc>

