Home Documents for HTTP APIsmnot@mnot.nethttp://www.mnot.net/
General
Internet-DraftThis document proposes a “home document” format for non-browser HTTP clients.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.There is an emerging preference for non-browser Web applications (colloquially, “HTTP APIs”) to use
a link-driven approach to their interactions to assure loose coupling, thereby enabling
extensibility 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, these APIs are documented by a document format like that is used as a
design-time description; i.e., the URIs and other information they describe are “baked into” client
implementations.In contrast, a “follow your nose” API advertises the resources available to clients using link
relations and the formats they support using internet media types . A client
can then decide – at run time – which resources to interact with 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, clients need to be able to discover this information quickly and efficiently use it to
interact with the server. Just as with a human-targeted “home page” for a site, we can create 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 home document format. This specification suggests one for consideration, using t
he JSON format .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
.A JSON Home Document uses the format described in and has the media type
“application/json-home”.Its content consists of a root object with a “resources” property, whose member names are link
relation types (as defined by ), and values are Resource Objects, defined below.For example:Here, we have a home document that 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 , 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 formats they accept, and the fact that they support
partial requests 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.:Note that the examples above use both tag and http URIs; any URI scheme can be used to identify link relations and other artefacts in home documents.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 .Templated links are indicated with an “href-template” property, whose value is a URI Template
. When “href-template” is present, the Resource Object MUST have a “href-vars” 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” refer to are URI-references
whose base URI is that of the JSON Home Document itself.Resource Objects MAY also have a “hints” property, whose value is an object that uses named
Resource Hints (see ) as its properties.A URI can be derived from a Templated Link by treating the “href-template” value as a Level 3 URI
Template , using the “href-vars” property to fill the template.The “href-vars” 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:If you understand that “http://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/widgets/12345” (assuming that the Home Document is located at
“http://example.org/”).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” link relation).This specification defines a set of common hints, based upon information that’s discoverable by
directly interacting with resources. See for information on defining new
hints.Resource Hint Name: allowDescription: 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.Specification: [this document]Content MUST be an array of strings, containing HTTP methods.Resource Hint Name: formatsDescription: Hints the representation types that the resource produces and consumes, using the
GET and PUT methods respectively, subject to the ‘allow’ hint.Specification: [this document]Content MUST be an object, whose keys are media types, and values are objects
containing Representation Hints (see ).Resource Hint Name: accept-patchDescription: Hints the PATCH request formats accepted by the resource for this
client; equivalent to the Accept-Patch HTTP response header.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.Resource Hint Name: accept-postDescription: Hints the POST request formats accepted by the resource for this client.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.Resource Hint Name: accept-rangesDescription: Hints the range-specifiers available to the client for this resource; equivalent to
the Accept-Ranges HTTP response header .Specification: [this document]Content MUST be an array of strings, containing HTTP range-specifiers.Resource Hint Name: accept-preferDescription: Hints the preferences supported by the resource. Note that, as per that
specifications, a preference can be ignored by the server.Specification: [this document]Content MUST be an array of strings, contain preferences.Resource Hint Name: docsDescription: Hints the location for human-readable documentation for the relation type of the
resource.Specification: [this document]Content MUST be a string containing an absolute-URI referring to documentation that
SHOULD be in HTML format.Resource Hint Name: precondition-reqDescription: Hints that the resource requires state-changing requests (e.g., PUT, PATCH) to
include a precondition, as per , to avoid conflicts due to concurrent updates.Specification: [this document]Content MUST be an array of strings, with possible values “etag” and “last-modified” indicating
type of precondition expected.Resource Hint Name: auth-reqDescription: Hints that the resource requires authentication using the HTTP Authentication
Framework .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:Resource Hint Name: statusDescription: Hints the status of the resource.Specification: [this document]Content MUST be a string; possible values are:“deprecated” - indicates that use of the resource is not recommended, but it is still available.“gone” - indicates that the resource is no longer available; i.e., it will return a 410 Gone HTTP
status code if accessed.TBDWhen making a home document available, there are a few things to keep in mind:A home document is best located at a memorable URI, because its URI will effectively become the
URI for the API itself to clients.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.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.Custom link relation types, as well as the URIs for variables, should lead to documentation for
those constructs.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:Reducing the freshness lifetime of home documents before a link change, so that clients are less
likely to refer to an “old” document.Regarding the “old” and “new” URIs as equally valid references for an “overlap” period.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.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.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.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 .As a result, clients SHOULD cache the home document (as per ), 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.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.This specification defines the HTTP Resource Hint Registry. See 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 constructs.New hints are registered using the Expert Review process described in to enforce the
criteria above. Requests for registration of new resource hints are to use the following template:Resource Hint Name: [hint name]Description: [a short description of the hint’s semantics]Specification: [reference to specification document]Initial registrations are enumerated in .TBDTBDKey words for use in RFCs to Indicate Requirement LevelsIn 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.Uniform Resource Identifier (URI): Generic SyntaxA 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]Guidelines for Writing an IANA Considerations Section in RFCsMany 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).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.This document obsoletes RFC 2434. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.Web LinkingThis 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]URI TemplateA 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]The JavaScript Object Notation (JSON) Data Interchange FormatJavaScript 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.This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance.Hypertext Transfer Protocol (HTTP/1.1): CachingThe 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.PATCH Method for HTTPSeveral 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]Media Type Specifications and Registration ProceduresThis 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.Hypertext Transfer Protocol (HTTP/1.1): Conditional RequestsThe 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.Hypertext Transfer Protocol (HTTP/1.1): Range RequestsThe 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.Hypertext Transfer Protocol (HTTP/1.1): AuthenticationThe Hypertext Transfer Protocol (HTTP) is a stateless application- level protocol for distributed, collaborative, hypermedia information systems. This document defines the HTTP Authentication framework.Prefer Header for HTTPThis 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.Web Application Description LanguageSun MicrosystemsMicroformatsmicroformats.orgThe 'tag' URI SchemeThis document describes the "tag" Uniform Resource Identifier (URI) scheme. Tag URIs (also known as "tags") 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 "http" URIs as identifiers for non-HTTP-accessible resources. This memo provides information for the Internet community.Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and RoutingThe 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 "http" and "https" Uniform Resource Identifier (URI) schemes, defines the HTTP/1.1 message syntax and parsing requirements, and describes related security concerns for implementations.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.Browser-centric Web applications use HTML as their representation format of choice. While it is
possible to augment HTML for non-browser clients (using techniques like Microformats
), a few issues become evident when doing so:HTML has a very forgiving syntax. While this is appropriate for browsers (especially considering
that there are many million HTML authors in the world), it makes for a less-than-precise language
for machines, resulting in both overhead (parsing and transmission) as well as lack of precision.HTML is presentation-centric, making it tempting to reformat it from time to time, to improve the
“look and feel” of a page. However, doing so can cause comparatively brittle non-browser clients
to lose their understanding of the content’s semantics, unless very careful controls are in place.Because of this, it’s most practical to define a separate format, and JSON is easily
machine-readable, precise, and has a better chance of being managed for stability.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.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.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.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.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.The following is a list of placeholders for open issues.top-level object(s)
contact detailsoverall documentationrelease info?ToSrate limiting (per-resource?)Resource Hints
indicate a POST to 201 Created patternindicate an “action” POSToutbound linksforms?Representation Hints
format profilesdeprecationDefining new top-level and resource object properties - how new ones are minted, registry, etc.Discovery (e.g., conneg, .well-known, etc.)LIMITED include function?