One document matched: draft-nottingham-json-home-03.xml
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="../Tools/rfc2629xslt/rfc2629.xslt" ?>
<!DOCTYPE rfc SYSTEM "../Tools/rfc2629xslt/rfc2629.dtd">
<rfc ipr="trust200902" docName="draft-nottingham-json-home-03" category="info">
<?rfc toc="yes"?>
<?rfc tocindent="yes"?>
<?rfc sortrefs="yes"?>
<?rfc symrefs="yes"?>
<?rfc strict="yes"?>
<?rfc compact="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<front>
<title>Home Documents for HTTP APIs</title>
<author initials="M." surname="Nottingham" fullname="Mark Nottingham">
<organization/>
<address>
<email>mnot@mnot.net</email>
<uri>http://www.mnot.net/</uri>
</address>
</author>
<date year="2013"/>
<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>This draft should be discussed on the apps-discuss mailing list; see
<xref target="apps-discuss"/>.</t>
</note>
</front>
<middle>
<section anchor="introduction" title="Introduction">
<t>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.</t>
<t>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.</t>
<t>Sometimes, these APIs are documented by a document format like <xref target="WADL"/> that
is used as a design-time description; i.e., the URIs and other information
they describe are “baked into” client implementations.</t>
<t>In contrast, a “follow your nose” API advertises the resources available to
clients using link relations <xref target="RFC5988"/> and the formats they support using
internet media types <xref target="RFC6838"/>. 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.</t>
<t>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.</t>
<t>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 the JSON format <xref target="RFC4627"/>.</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="json-home-documents" title="JSON Home Documents">
<t>A JSON Home Document uses the format described in <xref target="RFC4627"/> and has the
media type “application/json-home”.</t>
<t>Its content consists of a root object with a “resources” property, whose
member names are link relation types (as defined by <xref target="RFC5988"/>), and values
are Resource Objects, defined below.</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
{
"resources": {
"http://example.org/rel/widgets": {
"href": "/widgets/"
},
"http://example.org/rel/widget": {
"href-template": "/widgets/{widget_id}",
"href-vars": {
"widget_id": "http://example.org/param/widget"
},
"hints": {
"allow": ["GET", "PUT", "DELETE", "PATCH"],
"formats": {
"application/json": {}
},
"accept-patch": ["application/json-patch"],
"accept-post": ["application/xml"],
"accept-ranges": ["bytes"]
}
}
}
}
]]></artwork>
</figure>
<t>Here, we have a home document that links to a resource, “/widgets/” with the
relation “http://example.org/rel/widgets”. It also links to an unknown
number of resources with the relation type “http://example.org/rel/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 formats they
accept, and the fact that they support partial requests
<xref target="I-D.ietf-httpbis-p5-range"/> 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": {
"http://example.org/rel/search-by-id": {
"href-template": "/search?id={widget}",
"href-vars": {
"widget_name": "http://example.org/param/widget"
}
},
"http://example.org/rel/search-by-name": {
"href-template": "/search?name={widget_name}",
"href-vars": {
"widget_name": "http://example.org/param/widget_name"
}
}
}
}
]]></artwork>
</figure>
</section>
<section anchor="resource-objects" title="Resource Objects">
<t>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.</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 “href-template” property, whose value is
a URI Template <xref target="RFC6570"/>. When “href-template” is present, the Resource
Object MUST have a “href-vars” property; see “Resolving Templated Links”.</t>
<t>Resource Objects MUST have exactly one of the “href” and “href-vars”
properties.</t>
<t>In both forms, the links that “href” and “href-template” refer to are
URI-references <xref target="RFC3986"/> whose base URI is that of the JSON 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 “href-template”
value as a Level 3 URI Template <xref target="RFC6570"/>, using the “href-vars” property to
fill the template.</t>
<t>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.</t>
<t>For example, given the following Resource Object:</t>
<figure>
<artwork><![CDATA[
"http://example.org/rel/widget": {
"href-template": "/widgets/{widget_id}",
"href-vars": {
"widget_id": "http://example.org/param/widget"
},
"hints": {
"allow": ["GET", "PUT", "DELETE", "PATCH"],
"formats": {
"application/json": {}
},
"accept-patch": ["application/json-patch"],
"accept-post": ["application/xml"],
"accept-ranges": ["bytes"]
}
}
]]></artwork>
</figure>
<t>If you understand that “http://example.org/param/widget” is an numeric
identifier for a widget (perhaps by dereferencing that URL and reading the
documentation), 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/”).</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 optimising communications, as well
as advertising available behaviours (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 behaviour 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.</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 produces and
consumes, using the GET and PUT methods respectively, subject to the ‘allow’
hint.</t>
<t>Specification: [this document]</t>
</list>
</t>
<t>Content MUST be an object, whose keys are media types, and values are objects
containing Representation Hints (see <xref target="representation_hints"/>).</t>
</section>
<section anchor="accept-patch" title="accept-patch">
<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="accept-post" title="accept-post">
<t>
<list style="symbols">
<t>Resource Hint Name: accept-post</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="accept-ranges" title="accept-ranges">
<t>
<list style="symbols">
<t>Resource Hint Name: accept-ranges</t>
<t>Description: Hints the range-specifiers available to the client for this
resource; equivalent to the Accept-Ranges HTTP response header
<xref target="I-D.ietf-httpbis-p5-range"/>.</t>
<t>Specification: [this document]</t>
</list>
</t>
<t>Content MUST be an array of strings, containing HTTP range-specifiers. </t>
</section>
<section anchor="accept-prefer" title="accept-prefer">
<t>
<list style="symbols">
<t>Resource Hint Name: accept-prefer</t>
<t>Description: Hints the preferences <xref target="I-D.snell-http-prefer"/> 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, contain 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="precondition-req" title="precondition-req">
<t>
<list style="symbols">
<t>Resource Hint Name: precondition-req</t>
<t>Description: Hints that the resource requires state-changing requests (e.g.,
PUT, PATCH) to include a precondition, as per
<xref target="I-D.ietf-httpbis-p4-conditional"/>, 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="auth-req" title="auth-req">
<t>
<list style="symbols">
<t>Resource Hint Name: auth-req</t>
<t>Description: Hints that the resource requires authentication using the HTTP
Authentication Framework <xref target="I-D.ietf-httpbis-p7-auth"/>.</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[
{
"auth-req": [
{
"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 410 Gone HTTP status code if accessed.</t>
</list>
</t>
</section>
</section>
<section anchor="representation_hints" title="Representation Hints">
<t>TBD</t>
</section>
<section anchor="creating-and-serving-home-documents" title="Creating and Serving Home Documents">
<t>When making a 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 personalised, 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 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.</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 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 SHOULD 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 anchor="documenting-apis-that-use-home-documents" title="Documenting APIs that use Home Documents">
<t>Another use case for “static” API description formats like WSDL and WADL is to
generate documentation for the API from them.</t>
<t>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.</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 optimise 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="I-D.ietf-httpbis-p6-cache"/>.</t>
<t>As a result, clients SHOULD cache the home document (as per
<xref target="I-D.ietf-httpbis-p6-cache"/>), 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 SHOULD obtain a
fresh copy of the home document, to assure that it is up-to-date.</t>
</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="RFC4627"/> 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="representation_hint_registry" title="HTTP Representation Hint Registry">
<t>TBD</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">
<front>
<title abbrev="RFC Key Words">Key words for use in RFCs to Indicate Requirement Levels</title>
<author initials="S." surname="Bradner" fullname="Scott Bradner">
<organization>Harvard University</organization>
<address>
<postal>
<street>1350 Mass. Ave.</street>
<street>Cambridge</street>
<street>MA 02138</street>
</postal>
<phone>- +1 617 495 3864</phone>
<email>sob@harvard.edu</email>
</address>
</author>
<date year="1997" month="March"/>
<area>General</area>
<keyword>keyword</keyword>
<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. Authors who follow these guidelines
should incorporate this phrase near the beginning of their document:
<list><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
RFC 2119.
</t></list></t>
<t>
Note that the force of these words is modified by the requirement
level of the document in which they are used.
</t>
</abstract>
</front>
<seriesInfo name="BCP" value="14"/>
<seriesInfo name="RFC" value="2119"/>
<format type="TXT" octets="4723" target="http://www.rfc-editor.org/rfc/rfc2119.txt"/>
<format type="HTML" octets="17970" target="http://xml.resource.org/public/rfc/html/rfc2119.html"/>
<format type="XML" octets="5777" target="http://xml.resource.org/public/rfc/xml/rfc2119.xml"/>
</reference>
<reference anchor="RFC3986">
<front>
<title abbrev="URI Generic Syntax">Uniform Resource Identifier (URI): Generic Syntax</title>
<author initials="T." surname="Berners-Lee" fullname="Tim Berners-Lee">
<organization abbrev="W3C/MIT">World Wide Web Consortium</organization>
<address>
<postal>
<street>Massachusetts Institute of Technology</street>
<street>77 Massachusetts Avenue</street>
<city>Cambridge</city>
<region>MA</region>
<code>02139</code>
<country>USA</country>
</postal>
<phone>+1-617-253-5702</phone>
<facsimile>+1-617-258-5999</facsimile>
<email>timbl@w3.org</email>
<uri>http://www.w3.org/People/Berners-Lee/</uri>
</address>
</author>
<author initials="R." surname="Fielding" fullname="Roy T. Fielding">
<organization abbrev="Day Software">Day Software</organization>
<address>
<postal>
<street>5251 California Ave., Suite 110</street>
<city>Irvine</city>
<region>CA</region>
<code>92617</code>
<country>USA</country>
</postal>
<phone>+1-949-679-2960</phone>
<facsimile>+1-949-679-2972</facsimile>
<email>fielding@gbiv.com</email>
<uri>http://roy.gbiv.com/</uri>
</address>
</author>
<author initials="L." surname="Masinter" fullname="Larry Masinter">
<organization abbrev="Adobe Systems">Adobe Systems Incorporated</organization>
<address>
<postal>
<street>345 Park Ave</street>
<city>San Jose</city>
<region>CA</region>
<code>95110</code>
<country>USA</country>
</postal>
<phone>+1-408-536-3024</phone>
<email>LMM@acm.org</email>
<uri>http://larry.masinter.net/</uri>
</address>
</author>
<date year="2005" month="January"/>
<area>Applications</area>
<keyword>uniform resource identifier</keyword>
<keyword>URI</keyword>
<keyword>URL</keyword>
<keyword>URN</keyword>
<keyword>WWW</keyword>
<keyword>resource</keyword>
<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.
</t>
</abstract>
</front>
<seriesInfo name="STD" value="66"/>
<seriesInfo name="RFC" value="3986"/>
<format type="TXT" octets="141811" target="http://www.rfc-editor.org/rfc/rfc3986.txt"/>
<format type="HTML" octets="214067" target="http://xml.resource.org/public/rfc/html/rfc3986.html"/>
<format type="XML" octets="163534" target="http://xml.resource.org/public/rfc/xml/rfc3986.xml"/>
</reference>
<reference anchor="RFC4627">
<front>
<title>The application/json Media Type for JavaScript Object Notation (JSON)</title>
<author initials="D." surname="Crockford" fullname="D. Crockford">
<organization/>
</author>
<date year="2006" month="July"/>
<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. This memo provides information for the Internet community.</t>
</abstract>
</front>
<seriesInfo name="RFC" value="4627"/>
<format type="TXT" octets="16319" target="http://www.rfc-editor.org/rfc/rfc4627.txt"/>
</reference>
<reference anchor="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"/>
<format type="TXT" octets="66160" target="http://www.rfc-editor.org/rfc/rfc5226.txt"/>
</reference>
<reference anchor="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"/>
<format type="TXT" octets="46834" target="http://www.rfc-editor.org/rfc/rfc5988.txt"/>
</reference>
<reference anchor="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"/>
<format type="TXT" octets="79813" target="http://www.rfc-editor.org/rfc/rfc6570.txt"/>
</reference>
<reference anchor="I-D.ietf-httpbis-p6-cache">
<front>
<title>Hypertext Transfer Protocol (HTTP/1.1): Caching</title>
<author initials="R" surname="Fielding" fullname="Roy Fielding">
<organization/>
</author>
<author initials="M" surname="Nottingham" fullname="Mark Nottingham">
<organization/>
</author>
<author initials="J" surname="Reschke" fullname="Julian Reschke">
<organization/>
</author>
<date month="February" day="23" year="2013"/>
<abstract>
<t>The Hypertext Transfer Protocol (HTTP) is an application-level protocol for distributed, collaborative, hypertext information systems. This document defines requirements on HTTP caches and the associated header fields that control cache behavior or indicate cacheable response messages.</t>
</abstract>
</front>
<seriesInfo name="Internet-Draft" value="draft-ietf-httpbis-p6-cache-22"/>
<format type="TXT" target="http://www.ietf.org/internet-drafts/draft-ietf-httpbis-p6-cache-22.txt"/>
</reference>
</references>
<references title="Informative References">
<reference anchor="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"/>
<format type="TXT" octets="21706" target="http://www.rfc-editor.org/rfc/rfc5789.txt"/>
</reference>
<reference anchor="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"/>
<format type="TXT" octets="72942" target="http://www.rfc-editor.org/rfc/rfc6838.txt"/>
</reference>
<reference anchor="I-D.ietf-httpbis-p4-conditional">
<front>
<title>Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests</title>
<author initials="R" surname="Fielding" fullname="Roy Fielding">
<organization/>
</author>
<author initials="J" surname="Reschke" fullname="Julian Reschke">
<organization/>
</author>
<date month="February" day="23" year="2013"/>
<abstract>
<t>The Hypertext Transfer Protocol (HTTP) is an 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="Internet-Draft" value="draft-ietf-httpbis-p4-conditional-22"/>
<format type="TXT" target="http://www.ietf.org/internet-drafts/draft-ietf-httpbis-p4-conditional-22.txt"/>
</reference>
<reference anchor="I-D.ietf-httpbis-p5-range">
<front>
<title>Hypertext Transfer Protocol (HTTP/1.1): Range Requests</title>
<author initials="R" surname="Fielding" fullname="Roy Fielding">
<organization/>
</author>
<author initials="Y" surname="Lafon" fullname="Yves Lafon">
<organization/>
</author>
<author initials="J" surname="Reschke" fullname="Julian Reschke">
<organization/>
</author>
<date month="February" day="23" year="2013"/>
<abstract>
<t>The Hypertext Transfer Protocol (HTTP) is an 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="Internet-Draft" value="draft-ietf-httpbis-p5-range-22"/>
<format type="TXT" target="http://www.ietf.org/internet-drafts/draft-ietf-httpbis-p5-range-22.txt"/>
</reference>
<reference anchor="I-D.ietf-httpbis-p7-auth">
<front>
<title>Hypertext Transfer Protocol (HTTP/1.1): Authentication</title>
<author initials="R" surname="Fielding" fullname="Roy Fielding">
<organization/>
</author>
<author initials="J" surname="Reschke" fullname="Julian Reschke">
<organization/>
</author>
<date month="February" day="23" year="2013"/>
<abstract>
<t>The Hypertext Transfer Protocol (HTTP) is an application-level protocol for distributed, collaborative, hypermedia information systems. This document defines the HTTP Authentication framework.</t>
</abstract>
</front>
<seriesInfo name="Internet-Draft" value="draft-ietf-httpbis-p7-auth-22"/>
<format type="TXT" target="http://www.ietf.org/internet-drafts/draft-ietf-httpbis-p7-auth-22.txt"/>
</reference>
<reference anchor="I-D.snell-http-prefer">
<front>
<title>Prefer Header for HTTP</title>
<author initials="J" surname="Snell" fullname="James Snell">
<organization/>
</author>
<date month="January" day="7" year="2013"/>
<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="Internet-Draft" value="draft-snell-http-prefer-18"/>
<format type="TXT" target="http://www.ietf.org/internet-drafts/draft-snell-http-prefer-18.txt"/>
</reference>
<reference anchor="WADL" target="http://www.w3.org/Submission/wadl/">
<front>
<title>Web Application Description Language</title>
<author initials="M." surname="Hadley">
<organization/>
</author>
<author>
<organization>Sun Microsystems</organization>
</author>
</front>
</reference>
<reference anchor="MICROFORMATS" target="http://microformats.org/">
<front>
<title>Microformats</title>
<author>
<organization>microformats.org</organization>
</author>
</front>
</reference>
<reference anchor="apps-discuss" target="https://www.ietf.org/mailman/listinfo/apps-discuss">
<front>
<title>IETF Apps-Discuss Mailing List</title>
<author>
<organization>IETF</organization>
</author>
</front>
</reference>
</references>
<section anchor="acknowledgements" title="Acknowledgements">
<t>Thanks to Jan Algermissen, Mike Amundsen, Bill Burke, Graham Klyne, Leif
Hedstrom, Jeni Tennison, Erik Wilde and Jorge Williams for their suggestions
and feedback.</t>
</section>
<section anchor="frequently-asked-questions" title="Frequently Asked Questions">
<section anchor="why-not-microformats" title="Why not Microformats?">
<t>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 <xref target="MICROFORMATS"/>), a few issues become evident
when doing so:</t>
<t>
<list style="symbols">
<t>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.</t>
<t>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.</t>
</list>
</t>
<t>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.</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-authentication" title="What about authentication?">
<t>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.</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.</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>
<section anchor="open-issues" title="Open Issues">
<t>The following is a list of placeholders for open issues.</t>
<t>
<list style="symbols">
<t>top-level object(s)
<list style="symbols"><t>contact details</t><t>overall documentation</t><t>release info?</t><t>ToS</t><t>rate limiting (per-resource?)</t></list></t>
<t>Resource Hints
<list style="symbols"><t>indicate a POST to 201 Created pattern</t><t>indicate an “action” POST</t><t>outbound links</t><t>forms?</t></list></t>
<t>Representation Hints
<list style="symbols"><t>format profiles</t><t>deprecation</t></list></t>
<t>Defining new top-level and resource object properties - how new ones are minted, registry, etc.</t>
<t>Discovery (e.g., conneg, .well-known, etc.)</t>
<t>LIMITED include function?</t>
</list>
</t>
</section>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-24 01:08:09 |