< draft-nottingham-json-home-03.txt   draft-nottingham-json-home-04.txt >
Network Working Group M. Nottingham Network Working Group M. Nottingham
Internet-Draft May 8, 2013 Internet-Draft May 23, 2016
Intended status: Informational Intended status: Informational
Expires: November 9, 2013 Expires: November 24, 2016
Home Documents for HTTP APIs Home Documents for HTTP APIs
draft-nottingham-json-home-03 draft-nottingham-json-home-04
Abstract Abstract
This document proposes a "home document" format for non-browser HTTP This document proposes a "home document" format for non-browser HTTP
clients. clients.
Note to Readers Note to Readers
This draft should be discussed on the apps-discuss mailing list; see The issues list for this draft can be found at
[apps-discuss]. https://github.com/mnot/I-D/labels/json-home .
Status of this Memo The most recent (often, unpublished) draft is at
https://mnot.github.io/I-D/json-home/ .
Recent changes are listed at https://github.com/mnot/I-D/commits/gh-
pages/json-home .
For information about implementations, see https://github.com/mnot/I-
D/wiki/json-home .
Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on November 9, 2013. This Internet-Draft will expire on November 24, 2016.
Copyright Notice Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the Copyright (c) 2016 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4
2. JSON Home Documents . . . . . . . . . . . . . . . . . . . . . 3 2. JSON Home Documents . . . . . . . . . . . . . . . . . . . . . 4
3. Resource Objects . . . . . . . . . . . . . . . . . . . . . . . 5 3. Resource Objects . . . . . . . . . . . . . . . . . . . . . . 5
3.1. Resolving Templated Links . . . . . . . . . . . . . . . . 6 3.1. Resolving Templated Links . . . . . . . . . . . . . . . . 6
4. Resource Hints . . . . . . . . . . . . . . . . . . . . . . . . 6 4. Resource Hints . . . . . . . . . . . . . . . . . . . . . . . 7
4.1. allow . . . . . . . . . . . . . . . . . . . . . . . . . . 7 4.1. allow . . . . . . . . . . . . . . . . . . . . . . . . . . 8
4.2. formats . . . . . . . . . . . . . . . . . . . . . . . . . 7 4.2. formats . . . . . . . . . . . . . . . . . . . . . . . . . 8
4.3. accept-patch . . . . . . . . . . . . . . . . . . . . . . . 7 4.3. accept-patch . . . . . . . . . . . . . . . . . . . . . . 8
4.4. accept-post . . . . . . . . . . . . . . . . . . . . . . . 8 4.4. accept-post . . . . . . . . . . . . . . . . . . . . . . . 8
4.5. accept-ranges . . . . . . . . . . . . . . . . . . . . . . 8 4.5. accept-ranges . . . . . . . . . . . . . . . . . . . . . . 9
4.6. accept-prefer . . . . . . . . . . . . . . . . . . . . . . 8 4.6. accept-prefer . . . . . . . . . . . . . . . . . . . . . . 9
4.7. docs . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 4.7. docs . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4.8. precondition-req . . . . . . . . . . . . . . . . . . . . . 9 4.8. precondition-req . . . . . . . . . . . . . . . . . . . . 9
4.9. auth-req . . . . . . . . . . . . . . . . . . . . . . . . . 9 4.9. auth-req . . . . . . . . . . . . . . . . . . . . . . . . 10
4.10. status . . . . . . . . . . . . . . . . . . . . . . . . . . 9 4.10. status . . . . . . . . . . . . . . . . . . . . . . . . . 10
5. Representation Hints . . . . . . . . . . . . . . . . . . . . . 10 5. Representation Hints . . . . . . . . . . . . . . . . . . . . 11
6. Creating and Serving Home Documents . . . . . . . . . . . . . 10 6. Creating and Serving Home Documents . . . . . . . . . . . . . 11
6.1. Managing Change in Home Documents . . . . . . . . . . . . 10 6.1. Managing Change in Home Documents . . . . . . . . . . . . 11
6.2. Evolving and Mixing APIs with Home Documents . . . . . . . 11 6.2. Evolving and Mixing APIs with Home Documents . . . . . . 12
6.3. Documenting APIs that use Home Documents . . . . . . . . . 11 6.3. Documenting APIs that use Home Documents . . . . . . . . 12
7. Consuming Home Documents . . . . . . . . . . . . . . . . . . . 11 7. Consuming Home Documents . . . . . . . . . . . . . . . . . . 12
8. Security Considerations . . . . . . . . . . . . . . . . . . . 12 8. Security Considerations . . . . . . . . . . . . . . . . . . . 13
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13
9.1. HTTP Resource Hint Registry . . . . . . . . . . . . . . . 12 9.1. HTTP Resource Hint Registry . . . . . . . . . . . . . . . 13
9.2. HTTP Representation Hint Registry . . . . . . . . . . . . 12 9.2. HTTP Representation Hint Registry . . . . . . . . . . . . 13
9.3. Media Type Registration . . . . . . . . . . . . . . . . . 12 9.3. Media Type Registration . . . . . . . . . . . . . . . . . 14
10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 14
10.1. Normative References . . . . . . . . . . . . . . . . . . . 13 10.1. Normative References . . . . . . . . . . . . . . . . . . 14
10.2. Informative References . . . . . . . . . . . . . . . . . . 13 10.2. Informative References . . . . . . . . . . . . . . . . . 14
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 14 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 15
Appendix B. Frequently Asked Questions . . . . . . . . . . . . . 14 Appendix B. Frequently Asked Questions . . . . . . . . . . . . . 16
B.1. Why not Microformats? . . . . . . . . . . . . . . . . . . 14 B.1. Why not Microformats? . . . . . . . . . . . . . . . . . . 16
B.2. Why doesn't the format allow references or inheritance? . 15 B.2. Why doesn't the format allow references or inheritance? . 16
B.3. What about authentication? . . . . . . . . . . . . . . . . 15 B.3. What about authentication? . . . . . . . . . . . . . . . 16
B.4. What about "Faults" (i.e., errors)? . . . . . . . . . . . 15 B.4. What about "Faults" (i.e., errors)? . . . . . . . . . . . 16
B.5. How Do I find the schema for a format? . . . . . . . . . . 15 B.5. How Do I find the schema for a format? . . . . . . . . . 17
B.6. How do I express complex query arguments? . . . . . . . . 15 B.6. How do I express complex query arguments? . . . . . . . . 17
Appendix C. Open Issues . . . . . . . . . . . . . . . . . . . . . 16 Appendix C. Open Issues . . . . . . . . . . . . . . . . . . . . 17
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 16 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 18
1. Introduction 1. Introduction
There is an emerging preference for non-browser Web applications There is an emerging preference for non-browser Web applications
(colloquially, "HTTP APIs") to use a link-driven approach to their (colloquially, "HTTP APIs") to use a link-driven approach to their
interactions to assure loose coupling, thereby enabling extensibility interactions to assure loose coupling, thereby enabling extensibility
and API evolution. and API evolution.
This is based upon experience with previous APIs that specified This is based upon experience with previous APIs that specified
static URI paths (such as static URI paths (such as
skipping to change at page 3, line 36 skipping to change at page 3, line 45
safely add new resources and formats without disturbing clients that safely add new resources and formats without disturbing clients that
are not yet aware of them. are not yet aware of them.
As such, clients need to be able to discover this information quickly 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 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 human-targeted "home page" for a site, we can create a "home
document" for a HTTP API that describes it to non-browser clients. 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 Of course, an HTTP API might use any format to do so; however, there
are advantages to having a standard home document format. This are advantages to having a standard home document format. This
specification suggests one for consideration, using the JSON format specification suggests one for consideration, using t he JSON format
[RFC4627]. [RFC7159].
1.1. Notational Conventions 1.1. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119]. document are to be interpreted as described in [RFC2119].
2. JSON Home Documents 2. JSON Home Documents
A JSON Home Document uses the format described in [RFC4627] and has A JSON Home Document uses the format described in [RFC7159] and has
the media type "application/json-home". the media type "application/json-home".
Its content consists of a root object with a "resources" property, Its content consists of a root object with a "resources" property,
whose member names are link relation types (as defined by [RFC5988]), whose member names are link relation types (as defined by [RFC5988]),
and values are Resource Objects, defined below. and values are Resource Objects, defined below.
For example: For example:
GET / HTTP/1.1 GET / HTTP/1.1
Host: example.org Host: example.org
Accept: application/json-home Accept: application/json-home
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json-home Content-Type: application/json-home
Cache-Control: max-age=3600 Cache-Control: max-age=3600
Connection: close Connection: close
{ {
"resources": { "resources": {
"http://example.org/rel/widgets": { "tag:me@example.com,2016:widgets": {
"href": "/widgets/" "href": "/widgets/"
}, },
"http://example.org/rel/widget": { "tag:me@example.com,2016:widget": {
"href-template": "/widgets/{widget_id}", "href-template": "/widgets/{widget_id}",
"href-vars": { "href-vars": {
"widget_id": "http://example.org/param/widget" "widget_id": "http://example.org/param/widget"
}, },
"hints": { "hints": {
"allow": ["GET", "PUT", "DELETE", "PATCH"], "allow": ["GET", "PUT", "DELETE", "PATCH"],
"formats": { "formats": {
"application/json": {} "application/json": {}
}, },
"accept-patch": ["application/json-patch"], "accept-patch": ["application/json-patch+json"],
"accept-post": ["application/xml"], "accept-post": ["application/xml"],
"accept-ranges": ["bytes"] "accept-ranges": ["bytes"]
} }
} }
} }
} }
Here, we have a home document that links to a resource, "/widgets/" Here, we have a home document that links to a resource, "/widgets/"
with the relation "http://example.org/rel/widgets". It also links to with the relation "tag:me@example.com,2016:widgets". It also links
an unknown number of resources with the relation type to an unknown number of resources with the relation type
"http://example.org/rel/widget" using a URI Template [RFC6570], along "tag:me@example.com,2016:widget" using a URI Template [RFC6570],
with a mapping of identifiers to a variable for use in that 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 It also gives several hints about interacting with the latter
"widget" resources, including the HTTP methods usable with them, the "widget" resources, including the HTTP methods usable with them, the
patch formats they accept, and the fact that they support partial patch formats they accept, and the fact that they support partial
requests [I-D.ietf-httpbis-p5-range] using the "bytes" range- requests [RFC7233] using the "bytes" range-specifier.
specifier.
It gives no such hints about the "widgets" resource. This does not 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 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 that the client will need to discover this by interacting with the
resource, and/or examining the documentation for its link relation resource, and/or examining the documentation for its link relation
type. type.
Effectively, this names a set of behaviors, as described by a Effectively, this names a set of behaviors, as described by a
resource object, with a link relation type. This means that several resource object, with a link relation type. This means that several
link relations might apply to a common base URL; e.g.: link relations might apply to a common base URL; e.g.:
{ {
"resources": { "resources": {
"http://example.org/rel/search-by-id": { "tag:me@example.com,2016:search-by-id": {
"href-template": "/search?id={widget}", "href-template": "/search?id={widget_id}",
"href-vars": { "href-vars": {
"widget_name": "http://example.org/param/widget" "widget_id": "http://example.org/param/widget_id"
} }
}, },
"http://example.org/rel/search-by-name": { "tag:me@example.com,2016:search-by-name": {
"href-template": "/search?name={widget_name}", "href-template": "/search?name={widget_name}",
"href-vars": { "href-vars": {
"widget_name": "http://example.org/param/widget_name" "widget_name": "http://example.org/param/widget_name"
} }
} }
} }
} }
Note that the examples above use both tag [RFC4151] and http
[RFC7230] URIs; any URI scheme can be used to identify link relations
and other artefacts in home documents.
3. Resource Objects 3. Resource Objects
A Resource Object links to resources of the defined type using one of 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 two mechanisms; either a direct link (in which case there is exactly
one resource of that relation type associated with the API), or a one resource of that relation type associated with the API), or a
templated link, in which case there are zero to many such resources. templated link, in which case there are zero to many such resources.
Direct links are indicated with an "href" property, whose value is a Direct links are indicated with an "href" property, whose value is a
URI [RFC3986]. URI [RFC3986].
skipping to change at page 6, line 33 skipping to change at page 7, line 15
"http://example.org/rel/widget": { "http://example.org/rel/widget": {
"href-template": "/widgets/{widget_id}", "href-template": "/widgets/{widget_id}",
"href-vars": { "href-vars": {
"widget_id": "http://example.org/param/widget" "widget_id": "http://example.org/param/widget"
}, },
"hints": { "hints": {
"allow": ["GET", "PUT", "DELETE", "PATCH"], "allow": ["GET", "PUT", "DELETE", "PATCH"],
"formats": { "formats": {
"application/json": {} "application/json": {}
}, },
"accept-patch": ["application/json-patch"], "accept-patch": ["application/json-patch+json"],
"accept-post": ["application/xml"], "accept-post": ["application/xml"],
"accept-ranges": ["bytes"] "accept-ranges": ["bytes"]
} }
} }
If you understand that "http://example.org/param/widget" is an If you understand that "http://example.org/param/widget" is an
numeric identifier for a widget (perhaps by dereferencing that URL numeric identifier for a widget, you can then find the resource
and reading the documentation), you can then find the resource corresponding to widget number 12345 at "http://example.org/
corresponding to widget number 12345 at widgets/12345" (assuming that the Home Document is located at
"http://example.org/widgets/12345" (assuming that the Home Document "http://example.org/").
is located at "http://example.org/").
4. Resource Hints 4. Resource Hints
Resource hints allow clients to find relevant information about Resource hints allow clients to find relevant information about
interacting with a resource beforehand, as a means of optimising interacting with a resource beforehand, as a means of optimizing
communications, as well as advertising available behaviours (e.g., to communications, as well as advertising available behaviors (e.g., to
aid in laying out a user interface for consuming the API). 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 Hints are just that - they are not a "contract", and are to only be
taken as advisory. The runtime behaviour of the resource always taken as advisory. The runtime behavior of the resource always
overrides hinted information. overrides hinted information.
For example, a resource might hint that the PUT method is allowed on For example, a resource might hint that the PUT method is allowed on
all "widget" resources. This means that generally, the user has the all "widget" resources. This means that generally, the user has the
ability to PUT to a particular resource, but a specific resource ability to PUT to a particular resource, but a specific resource
might reject a PUT based upon access control or other considerations. might reject a PUT based upon access control or other considerations.
More fine-grained information might be gathered by interacting with More fine-grained information might be gathered by interacting with
the resource (e.g., via a GET), or by another resource "containing" the resource (e.g., via a GET), or by another resource "containing"
it (such as a "widgets" collection) or describing it (e.g., one it (such as a "widgets" collection) or describing it (e.g., one
linked to it with a "describedby" link relation). linked to it with a "describedby" link relation).
skipping to change at page 8, line 15 skipping to change at page 8, line 48
o Specification: [this document] o Specification: [this document]
Content MUST be an array of strings, containing media types. Content MUST be an array of strings, containing media types.
When this hint is present, "PATCH" SHOULD be listed in the "allow" When this hint is present, "PATCH" SHOULD be listed in the "allow"
hint. hint.
4.4. accept-post 4.4. accept-post
o Resource Hint Name: accept-post o Resource Hint Name: accept-post
o Description: Hints the POST request formats accepted by the o Description: Hints the POST request formats accepted by the
resource for this client. resource for this client.
o Specification: [this document]
o Specification: [this document]
Content MUST be an array of strings, containing media types. Content MUST be an array of strings, containing media types.
When this hint is present, "POST" SHOULD be listed in the "allow" When this hint is present, "POST" SHOULD be listed in the "allow"
hint. hint.
4.5. accept-ranges 4.5. accept-ranges
o Resource Hint Name: accept-ranges o Resource Hint Name: accept-ranges
o Description: Hints the range-specifiers available to the client o Description: Hints the range-specifiers available to the client
for this resource; equivalent to the Accept-Ranges HTTP response for this resource; equivalent to the Accept-Ranges HTTP response
header [I-D.ietf-httpbis-p5-range]. header [RFC7233].
o Specification: [this document] o Specification: [this document]
Content MUST be an array of strings, containing HTTP range- Content MUST be an array of strings, containing HTTP range-
specifiers. specifiers.
4.6. accept-prefer 4.6. accept-prefer
o Resource Hint Name: accept-prefer o Resource Hint Name: accept-prefer
o Description: Hints the preferences [I-D.snell-http-prefer]
supported by the resource. Note that, as per that specifications, o Description: Hints the preferences [RFC7240] supported by the
a preference can be ignored by the server. resource. Note that, as per that specifications, a preference can
be ignored by the server.
o Specification: [this document] o Specification: [this document]
Content MUST be an array of strings, contain preferences. Content MUST be an array of strings, contain preferences.
4.7. docs 4.7. docs
o Resource Hint Name: docs o Resource Hint Name: docs
o Description: Hints the location for human-readable documentation o Description: Hints the location for human-readable documentation
for the relation type of the resource. for the relation type of the resource.
o Specification: [this document] o Specification: [this document]
Content MUST be a string containing an absolute-URI [RFC3986] Content MUST be a string containing an absolute-URI [RFC3986]
referring to documentation that SHOULD be in HTML format. referring to documentation that SHOULD be in HTML format.
4.8. precondition-req 4.8. precondition-req
o Resource Hint Name: precondition-req o Resource Hint Name: precondition-req
o Description: Hints that the resource requires state-changing o Description: Hints that the resource requires state-changing
requests (e.g., PUT, PATCH) to include a precondition, as per requests (e.g., PUT, PATCH) to include a precondition, as per
[I-D.ietf-httpbis-p4-conditional], to avoid conflicts due to [RFC7232], to avoid conflicts due to concurrent updates.
concurrent updates.
o Specification: [this document] o Specification: [this document]
Content MUST be an array of strings, with possible values "etag" and Content MUST be an array of strings, with possible values "etag" and
"last-modified" indicating type of precondition expected. "last-modified" indicating type of precondition expected.
4.9. auth-req 4.9. auth-req
o Resource Hint Name: auth-req o Resource Hint Name: auth-req
o Description: Hints that the resource requires authentication using o Description: Hints that the resource requires authentication using
the HTTP Authentication Framework [I-D.ietf-httpbis-p7-auth]. the HTTP Authentication Framework [RFC7235].
o Specification: [this document] o Specification: [this document]
Content MUST be an array of objects, each with a "scheme" property Content MUST be an array of objects, each with a "scheme" property
containing a string that corresponds to a HTTP authentication scheme, containing a string that corresponds to a HTTP authentication scheme,
and optionally a "realms" property containing an array of zero to and optionally a "realms" property containing an array of zero to
many strings that identify protection spaces that the resource is a many strings that identify protection spaces that the resource is a
member of. member of.
For example, a Resource Object might contain the following hint: For example, a Resource Object might contain the following hint:
skipping to change at page 9, line 45 skipping to change at page 10, line 42
{ {
"scheme": "Basic", "scheme": "Basic",
"realms": ["private"] "realms": ["private"]
} }
] ]
} }
4.10. status 4.10. status
o Resource Hint Name: status o Resource Hint Name: status
o Description: Hints the status of the resource. o Description: Hints the status of the resource.
o Specification: [this document] o Specification: [this document]
Content MUST be a string; possible values are: Content MUST be a string; possible values are:
o "deprecated" - indicates that use of the resource is not o "deprecated" - indicates that use of the resource is not
recommended, but it is still available. recommended, but it is still available.
o "gone" - indicates that the resource is no longer available; i.e., o "gone" - indicates that the resource is no longer available; i.e.,
it will return a 410 Gone HTTP status code if accessed. it will return a 410 Gone HTTP status code if accessed.
5. Representation Hints 5. Representation Hints
TBD TBD
6. Creating and Serving Home Documents 6. Creating and Serving Home Documents
When making a home document available, there are a few things to keep When making a home document available, there are a few things to keep
in mind: in mind:
o A home document is best located at a memorable URI, because its o A home document is best located at a memorable URI, because its
URI will effectively become the URI for the API itself to clients. URI will effectively become the URI for the API itself to clients.
o Home documents can be personalised, just as "normal" home pages
o Home documents can be personalized, just as "normal" home pages
can. For example, you might advertise different URIs, and/or can. For example, you might advertise different URIs, and/or
different kinds of link relations, depending on the client's different kinds of link relations, depending on the client's
identity. identity.
o Home documents SHOULD be assigned a freshness lifetime (e.g., o Home documents SHOULD be assigned a freshness lifetime (e.g.,
"Cache-Control: max-age=3600") so that clients can cache them, to "Cache-Control: max-age=3600") so that clients can cache them, to
avoid having to fetch it every time the client interacts with the avoid having to fetch it every time the client interacts with the
service. service.
o Custom link relation types, as well as the URIs for variables, o Custom link relation types, as well as the URIs for variables,
should lead to documentation for those constructs. should lead to documentation for those constructs.
6.1. Managing Change in Home Documents 6.1. Managing Change in Home Documents
The URIs used in home documents MAY change over time. However, The URIs used in home documents MAY change over time. However,
changing them can cause issues for clients that are relying on cached changing them can cause issues for clients that are relying on cached
home documents containing old links. home documents containing old links.
To mitigate the impact of such changes, servers SHOULD consider: To mitigate the impact of such changes, servers SHOULD consider:
skipping to change at page 11, line 35 skipping to change at page 12, line 35
to do so, provided that the link relation types and media types it to do so, provided that the link relation types and media types it
uses are well-documented already. uses are well-documented already.
7. Consuming Home Documents 7. Consuming Home Documents
Clients might use home documents in a variety of ways. Clients might use home documents in a variety of ways.
In the most common case - actually consuming the API - the client In the most common case - actually consuming the API - the client
will scan the Resources Object for the link relation(s) that it is 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. interested in, and then to interact with the resource(s) referred to.
Resource Hints can be used to optimise communication with the client, 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 as well as to inform as to the permissible actions (e.g., whether PUT
is likely to be supported). is likely to be supported).
Note that the home document is a "living" document; it does not Note that the home document is a "living" document; it does not
represent a "contract", but rather is expected to be inspected before represent a "contract", but rather is expected to be inspected before
each interaction. In particular, links from the home document MUST each interaction. In particular, links from the home document MUST
NOT be assumed to be valid beyond the freshness lifetime of the home NOT be assumed to be valid beyond the freshness lifetime of the home
document, as per HTTP's caching model [I-D.ietf-httpbis-p6-cache]. document, as per HTTP's caching model [RFC7234].
As a result, clients SHOULD cache the home document (as per As a result, clients SHOULD cache the home document (as per
[I-D.ietf-httpbis-p6-cache]), to avoid fetching it before every [RFC7234]), to avoid fetching it before every interaction (which
interaction (which would otherwise be required). would otherwise be required).
Likewise, a client encountering a 404 Not Found on a link SHOULD 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- obtain a fresh copy of the home document, to assure that it is up-to-
date. date.
8. Security Considerations 8. Security Considerations
Clients need to exercise care when using hints. For example, a naive Clients need to exercise care when using hints. For example, a naive
client might send credentials to a server that uses the auth-req client might send credentials to a server that uses the auth-req
hint, without checking to see if those credentials are appropriate hint, without checking to see if those credentials are appropriate
skipping to change at page 12, line 30 skipping to change at page 13, line 30
In particular, resource hints are generic; that is, they are In particular, resource hints are generic; that is, they are
potentially applicable to any resource, not specific to one potentially applicable to any resource, not specific to one
application of HTTP, nor to one particular format. Generally, they application of HTTP, nor to one particular format. Generally, they
ought to be information that would otherwise be discoverable by ought to be information that would otherwise be discoverable by
interacting with the resource. interacting with the resource.
Hint names MUST be composed of the lowercase letters (a-z), digits Hint names MUST be composed of the lowercase letters (a-z), digits
(0-9), underscores ("_") and hyphens ("-"), and MUST begin with a (0-9), underscores ("_") and hyphens ("-"), and MUST begin with a
lowercase letter. lowercase letter.
Hint content SHOULD be described in terms of JSON [RFC4627] Hint content SHOULD be described in terms of JSON [RFC7159]
constructs. constructs.
New hints are registered using the Expert Review process described in New hints are registered using the Expert Review process described in
[RFC5226] to enforce the criteria above. Requests for registration [RFC5226] to enforce the criteria above. Requests for registration
of new resource hints are to use the following template: of new resource hints are to use the following template:
o Resource Hint Name: [hint name] o Resource Hint Name: [hint name]
o Description: [a short description of the hint's semantics] o Description: [a short description of the hint's semantics]
o Specification: [reference to specification document] o Specification: [reference to specification document]
Initial registrations are enumerated in Section 4. Initial registrations are enumerated in Section 4.
9.2. HTTP Representation Hint Registry 9.2. HTTP Representation Hint Registry
TBD TBD
9.3. Media Type Registration 9.3. Media Type Registration
TBD TBD
10. References 10. References
10.1. Normative References 10.1. Normative References
[I-D.ietf-httpbis-p6-cache]
Fielding, R., Nottingham, M., and J. Reschke, "Hypertext
Transfer Protocol (HTTP/1.1): Caching",
draft-ietf-httpbis-p6-cache-22 (work in progress),
February 2013.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, January 2005. RFC 3986, DOI 10.17487/RFC3986, January 2005,
<http://www.rfc-editor.org/info/rfc3986>.
[RFC4627] Crockford, D., "The application/json Media Type for
JavaScript Object Notation (JSON)", RFC 4627, July 2006.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226, IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008. DOI 10.17487/RFC5226, May 2008,
<http://www.rfc-editor.org/info/rfc5226>.
[RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. [RFC5988] Nottingham, M., "Web Linking", RFC 5988,
DOI 10.17487/RFC5988, October 2010,
<http://www.rfc-editor.org/info/rfc5988>.
[RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M.,
and D. Orchard, "URI Template", RFC 6570, March 2012. and D. Orchard, "URI Template", RFC 6570,
DOI 10.17487/RFC6570, March 2012,
10.2. Informative References <http://www.rfc-editor.org/info/rfc6570>.
[I-D.ietf-httpbis-p4-conditional]
Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
(HTTP/1.1): Conditional Requests",
draft-ietf-httpbis-p4-conditional-22 (work in progress),
February 2013.
[I-D.ietf-httpbis-p5-range] [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Fielding, R., Lafon, Y., and J. Reschke, "Hypertext Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March
Transfer Protocol (HTTP/1.1): Range Requests", 2014, <http://www.rfc-editor.org/info/rfc7159>.
draft-ietf-httpbis-p5-range-22 (work in progress),
February 2013.
[I-D.ietf-httpbis-p7-auth] [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Fielding, R. and J. Reschke, "Hypertext Transfer Protocol Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching",
(HTTP/1.1): Authentication", draft-ietf-httpbis-p7-auth-22 RFC 7234, DOI 10.17487/RFC7234, June 2014,
(work in progress), February 2013. <http://www.rfc-editor.org/info/rfc7234>.
[I-D.snell-http-prefer] 10.2. Informative References
Snell, J., "Prefer Header for HTTP",
draft-snell-http-prefer-18 (work in progress),
January 2013.
[MICROFORMATS] [MICROFORMATS]
microformats.org, "Microformats", microformats.org, "Microformats", n.d.,
<http://microformats.org/>. <http://microformats.org/>.
[RFC4151] Kindberg, T. and S. Hawke, "The 'tag' URI Scheme",
RFC 4151, DOI 10.17487/RFC4151, October 2005,
<http://www.rfc-editor.org/info/rfc4151>.
[RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP",
RFC 5789, March 2010. RFC 5789, DOI 10.17487/RFC5789, March 2010,
<http://www.rfc-editor.org/info/rfc5789>.
[RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type
Specifications and Registration Procedures", BCP 13, Specifications and Registration Procedures", BCP 13,
RFC 6838, January 2013. RFC 6838, DOI 10.17487/RFC6838, January 2013,
<http://www.rfc-editor.org/info/rfc6838>.
[RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Message Syntax and Routing",
RFC 7230, DOI 10.17487/RFC7230, June 2014,
<http://www.rfc-editor.org/info/rfc7230>.
[RFC7232] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Conditional Requests", RFC 7232,
DOI 10.17487/RFC7232, June 2014,
<http://www.rfc-editor.org/info/rfc7232>.
[RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed.,
"Hypertext Transfer Protocol (HTTP/1.1): Range Requests",
RFC 7233, DOI 10.17487/RFC7233, June 2014,
<http://www.rfc-editor.org/info/rfc7233>.
[RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Authentication", RFC 7235,
DOI 10.17487/RFC7235, June 2014,
<http://www.rfc-editor.org/info/rfc7235>.
[RFC7240] Snell, J., "Prefer Header for HTTP", RFC 7240,
DOI 10.17487/RFC7240, June 2014,
<http://www.rfc-editor.org/info/rfc7240>.
[WADL] Hadley, M. and Sun Microsystems, "Web Application [WADL] Hadley, M. and Sun Microsystems, "Web Application
Description Language", Description Language", n.d.,
<http://www.w3.org/Submission/wadl/>. <http://www.w3.org/Submission/wadl/>.
[apps-discuss]
IETF, "IETF Apps-Discuss Mailing List",
<https://www.ietf.org/mailman/listinfo/apps-discuss>.
Appendix A. Acknowledgements Appendix A. Acknowledgements
Thanks to Jan Algermissen, Mike Amundsen, Bill Burke, Graham Klyne, Thanks to Jan Algermissen, Mike Amundsen, Bill Burke, Sven Dietze,
Leif Hedstrom, Jeni Tennison, Erik Wilde and Jorge Williams for their Graham Klyne, Leif Hedstrom, Joe Hildebrand, Jeni Tennison, Erik
suggestions and feedback. Wilde and Jorge Williams for their suggestions and feedback.
Appendix B. Frequently Asked Questions Appendix B. Frequently Asked Questions
B.1. Why not Microformats? B.1. Why not Microformats?
Browser-centric Web applications use HTML as their representation Browser-centric Web applications use HTML as their representation
format of choice. While it is possible to augment HTML for non- format of choice. While it is possible to augment HTML for non-
browser clients (using techniques like Microformats [MICROFORMATS]), browser clients (using techniques like Microformats [MICROFORMATS]),
a few issues become evident when doing so: a few issues become evident when doing so:
 End of changes. 60 change blocks. 
136 lines changed or deleted 177 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/