< draft-nottingham-json-home-04.txt		draft-nottingham-json-home-05.txt >
	Network Working Group M. Nottingham		Network Working Group M. Nottingham
	Internet-Draft May 23, 2016		Internet-Draft November 24, 2016
	Intended status: Informational		Intended status: Informational
	Expires: November 24, 2016		Expires: May 28, 2017
	Home Documents for HTTP APIs		Home Documents for HTTP APIs
	draft-nottingham-json-home-04		draft-nottingham-json-home-05
	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
	The issues list for this draft can be found at		The issues list for this draft can be found at
	https://github.com/mnot/I-D/labels/json-home .		https://github.com/mnot/I-D/labels/json-home .
	skipping to change at page 1, line 45 ¶		skipping to change at page 1, line 45 ¶
	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 24, 2016.		This Internet-Draft will expire on May 28, 2017.
	Copyright Notice		Copyright Notice
	Copyright (c) 2016 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 . . . . . . . . . . . . . . . . . 4		1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4
	2. JSON Home Documents . . . . . . . . . . . . . . . . . . . . . 4		2. API Home Documents . . . . . . . . . . . . . . . . . . . . . 4
	3. Resource Objects . . . . . . . . . . . . . . . . . . . . . . 5		3. API Objects . . . . . . . . . . . . . . . . . . . . . . . . . 6
	3.1. Resolving Templated Links . . . . . . . . . . . . . . . . 6		4. Resource Objects . . . . . . . . . . . . . . . . . . . . . . 7
	4. Resource Hints . . . . . . . . . . . . . . . . . . . . . . . 7		4.1. Resolving Templated Links . . . . . . . . . . . . . . . . 7
	4.1. allow . . . . . . . . . . . . . . . . . . . . . . . . . . 8		5. Resource Hints . . . . . . . . . . . . . . . . . . . . . . . 8
	4.2. formats . . . . . . . . . . . . . . . . . . . . . . . . . 8		5.1. allow . . . . . . . . . . . . . . . . . . . . . . . . . . 9
	4.3. accept-patch . . . . . . . . . . . . . . . . . . . . . . 8		5.2. formats . . . . . . . . . . . . . . . . . . . . . . . . . 9
	4.4. accept-post . . . . . . . . . . . . . . . . . . . . . . . 8		5.3. acceptPatch . . . . . . . . . . . . . . . . . . . . . . . 9
	4.5. accept-ranges . . . . . . . . . . . . . . . . . . . . . . 9		5.4. acceptPost . . . . . . . . . . . . . . . . . . . . . . . 9
	4.6. accept-prefer . . . . . . . . . . . . . . . . . . . . . . 9		5.5. acceptRanges . . . . . . . . . . . . . . . . . . . . . . 10
	4.7. docs . . . . . . . . . . . . . . . . . . . . . . . . . . 9		5.6. acceptPrefer . . . . . . . . . . . . . . . . . . . . . . 10
	4.8. precondition-req . . . . . . . . . . . . . . . . . . . . 9		5.7. docs . . . . . . . . . . . . . . . . . . . . . . . . . . 10
	4.9. auth-req . . . . . . . . . . . . . . . . . . . . . . . . 10		5.8. preconditionRequired . . . . . . . . . . . . . . . . . . 10
	4.10. status . . . . . . . . . . . . . . . . . . . . . . . . . 10		5.9. authSchemes . . . . . . . . . . . . . . . . . . . . . . . 11
	5. Representation Hints . . . . . . . . . . . . . . . . . . . . 11		5.10. status . . . . . . . . . . . . . . . . . . . . . . . . . 11
	6. Creating and Serving Home Documents . . . . . . . . . . . . . 11		6. Security Considerations . . . . . . . . . . . . . . . . . . . 12
	6.1. Managing Change in Home Documents . . . . . . . . . . . . 11		7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12
	6.2. Evolving and Mixing APIs with Home Documents . . . . . . 12		7.1. HTTP Resource Hint Registry . . . . . . . . . . . . . . . 12
	6.3. Documenting APIs that use Home Documents . . . . . . . . 12		7.2. Media Type Registration . . . . . . . . . . . . . . . . . 13
	7. Consuming Home Documents . . . . . . . . . . . . . . . . . . 12		8. References . . . . . . . . . . . . . . . . . . . . . . . . . 13
	8. Security Considerations . . . . . . . . . . . . . . . . . . . 13		8.1. Normative References . . . . . . . . . . . . . . . . . . 13
	9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13		8.2. Informative References . . . . . . . . . . . . . . . . . 13
	9.1. HTTP Resource Hint Registry . . . . . . . . . . . . . . . 13		Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 14
	9.2. HTTP Representation Hint Registry . . . . . . . . . . . . 13		Appendix B. Considerations for Creating and Serving Home
	9.3. Media Type Registration . . . . . . . . . . . . . . . . . 14		Documents . . . . . . . . . . . . . . . . . . . . . 14
	10. References . . . . . . . . . . . . . . . . . . . . . . . . . 14		B.1. Managing Change in Home Documents . . . . . . . . . . . . 15
	10.1. Normative References . . . . . . . . . . . . . . . . . . 14		B.2. Evolving and Mixing APIs with Home Documents . . . . . . 15
	10.2. Informative References . . . . . . . . . . . . . . . . . 14		Appendix C. Considerations for Consuming Home Documents . . . . 16
	Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 15		Appendix D. Frequently Asked Questions . . . . . . . . . . . . . 16
	Appendix B. Frequently Asked Questions . . . . . . . . . . . . . 16		D.1. Why doesn't the format allow references or inheritance? . 16
	B.1. Why not Microformats? . . . . . . . . . . . . . . . . . . 16		D.2. What about "Faults" (i.e., errors)? . . . . . . . . . . . 16
	B.2. Why doesn't the format allow references or inheritance? . 16		D.3. How Do I find the schema for a format? . . . . . . . . . 17
	B.3. What about authentication? . . . . . . . . . . . . . . . 16		D.4. How do I express complex query arguments? . . . . . . . . 17
	B.4. What about "Faults" (i.e., errors)? . . . . . . . . . . . 16		Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 17
	B.5. How Do I find the schema for a format? . . . . . . . . . 17
	B.6. How do I express complex query arguments? . . . . . . . . 17
	Appendix C. Open Issues . . . . . . . . . . . . . . . . . . . . 17
	Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 18
	1. Introduction		1. Introduction
	There is an emerging preference for non-browser Web applications		It is becoming increasingly common to use HTTP [RFC7230] for
	(colloquially, "HTTP APIs") to use a link-driven approach to their		applications other than traditional Web browsing. Such "HTTP APIs"
	interactions to assure loose coupling, thereby enabling extensibility		are used to integrate processes on disparate systems, make
	and API evolution.		information available to machines across the Internet, and as part of
			the implementation of "micro-services."
	This is based upon experience with previous APIs that specified		By using HTTP, these applications realise a number of benefits, from
	static URI paths (such as		message framing to caching, and well-defined semantics that are
	"http://api.example.com/v1.0/widgets/abc123/properties"), which have		broadly understood and useful.
	resulted in brittle, tight coupling between clients and servers.
	Sometimes, these APIs are documented by a document format like [WADL]		However, one of the core architectural tenants of the Web is the use
	that is used as a design-time description; i.e., the URIs and other		of links [RFC3986] to navigate between states; typically, these
	information they describe are "baked into" client implementations.		applications document static URLs that clients need to know and
			servers need to implement, and any interaction outside of these
			bounds is uncharted territory.
	In contrast, a "follow your nose" API advertises the resources		In contrast, a link-driven application discovers relevant resources
	available to clients using link relations [RFC5988] and the formats		at run time, using a shared vocabulary of link relations [RFC5988]
	they support using internet media types [RFC6838]. A client can then		and internet media types [RFC6838] to support a "follow your nose"
	decide - at run time - which resources to interact with based upon		style of interaction.
	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		A client can then decide which resources to interact with "on the
	and efficiently use it to interact with the server. Just as with a		fly" based upon its capabilities (as described by link relations),
	human-targeted "home page" for a site, we can create a "home		and the server can safely add new resources and formats without
	document" for a HTTP API that describes it to non-browser clients.		disturbing clients that are not yet aware of them.
			Doing so can provide any of a number of benefits, including:
			o Extensibility - Because new server capabilities can be expressed
			as link relations, new features can be layered in without
			introducing a new API version; clients will discover them in the
			home document. This promotes loose coupling between clients and
			servers.
			o Evolvability - Likewise, interfaces can change gradually by
			introducing a new link relation and/or format while still
			supporting the old ones.
			o Customisation - Home documents can be tailored for the client,
			allowing diffrent classes of service or different client
			permissions to be exposed naturally.
			o Flexible deployment - Since URLs aren't baked into documentation,
			the server can choose what URLs to use for a given service.
			o API mixing - Likewise, more than one API can be deployed on a
			given server, without fear of collisions.
			Whether an application ought to use links in this fashion depends on
			how it is deployed; generally, the most benefit will be received when
			multiple instances of the service are deployed, possibly with
			different versions, and they are consumed by clients with different
			capabilities. In particular, Internet Standards that use HTTP as a
			substrate are likely to require the attributes described above.
			Clients need to be able to discover information about these
			applications to use it efficiently; just as with a human-targeted
			"home page" for a site, there is a need for a "home document" for a
			HTTP API that describes it to non-browser clients.
	Of course, an HTTP API might use any format to do so; however, there		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 common home document format. This
	specification suggests one for consideration, using t he JSON format		specification defines one, using the JSON format [RFC7159].
	[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. API Home Documents
	A JSON Home Document uses the format described in [RFC7159] and has		An API Home Document (or, interchangeably, "home document") uses the
	the media type "application/json-home".		format described in [RFC7159] and has 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:
	whose member names are link relation types (as defined by [RFC5988]),
	and values are Resource Objects, defined below.		o A "resources" member, whose value is an object that describes the
			resources associated with the API. Its member names are link
			relation types (as defined by [RFC5988]), and their values are
			Resource Objects (Section 4).
			o Optionally, a "api" member, whose value is an API Object
			(Section 3) that contains information about the API as a whole.
	For example:		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
	{		{
			"api": {
			"title": "Example API",
			"links": {
			"author": "mailto:api-admin@example.com",
			"describedBy": "https://example.com/api-docs/"
			}
			}
	"resources": {		"resources": {
	"tag:me@example.com,2016:widgets": {		"tag:me@example.com,2016:widgets": {
	"href": "/widgets/"		"href": "/widgets/"
	},		},
	"tag:me@example.com,2016:widget": {		"tag:me@example.com,2016:widget": {
	"href-template": "/widgets/{widget_id}",		"hrefTemplate": "/widgets/{widget_id}",
	"href-vars": {		"hrefVars": {
	"widget_id": "http://example.org/param/widget"		"widget_id": "https://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+json"],		"acceptPatch": ["application/json-patch+json"],
	"accept-post": ["application/xml"],		"acceptRanges": ["bytes"]
	"accept-ranges": ["bytes"]
	}		}
	}		}
	}		}
	}		}
	Here, we have a home document that links to a resource, "/widgets/"		Here, we have a home document for the API "Example API", whose author
	with the relation "tag:me@example.com,2016:widgets". It also links		can be contacted at the e-mail address "api-admin@example.com", and
	to an unknown number of resources with the relation type		whose documentation is at "https://example.com/api-docs/".
			It links to a resource "/widgets/" with the relation
			"tag:me@example.com,2016:widgets". It also links to an unknown
			number of resources with the relation type
	"tag:me@example.com,2016:widget" using a URI Template [RFC6570],		"tag:me@example.com,2016:widget" using a URI Template [RFC6570],
	along with a mapping of identifiers to a variable for use in that		along with a mapping of identifiers to a variable for use in that
	template.		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 and POST formats they accept, and the fact that they support
	requests [RFC7233] using the "bytes" range-specifier.		partial requests [RFC7233] using the "bytes" range-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": {
	"tag:me@example.com,2016:search-by-id": {		"tag:me@example.com,2016:search-by-id": {
	"href-template": "/search?id={widget_id}",		"hrefTemplate": "/search?id={widget_id}",
	"href-vars": {		"hrefVars": {
	"widget_id": "http://example.org/param/widget_id"		"widget_id": "https://example.org/param/widget_id"
	}		}
	},		},
	"tag:me@example.com,2016:search-by-name": {		"tag:me@example.com,2016:search-by-name": {
	"href-template": "/search?name={widget_name}",		"hrefTemplate": "/search?name={widget_name}",
	"href-vars": {		"hrefVars": {
	"widget_name": "http://example.org/param/widget_name"		"widget_name": "https://example.org/param/widget_name"
	}		}
	}		}
	}		}
	}		}
	Note that the examples above use both tag [RFC4151] and http		Note that the examples above use both tag [RFC4151] and https
	[RFC7230] URIs; any URI scheme can be used to identify link relations		[RFC7230] URIs; any URI scheme can be used to identify link relations
	and other artefacts in home documents.		and other artefacts in home documents.
	3. Resource Objects		3. API Objects
			An API Object contains links to information about the API itself.
			Two members are defined:
			o "title" has a string value indicating the name of the API;
			o "links" has an object value, whose member names are link relation
			types [RFC5988], and values are URLs [RFC3986]. The context of
			these links is the API home document as a whole.
			Future members MAY be defined by specifications that update this
			document.
			4. Resource Objects
	A Resource Object links to resources of the defined type using one of		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].
	Templated links are indicated with an "href-template" property, whose		Templated links are indicated with an "hrefTemplate" property, whose
	value is a URI Template [RFC6570]. When "href-template" is present,		value is a URI Template [RFC6570]. When "hrefTemplate" is present,
	the Resource Object MUST have a "href-vars" property; see "Resolving		the Resource Object MUST have a "hrefVars" property; see "Resolving
	Templated Links".		Templated Links".
	Resource Objects MUST have exactly one of the "href" and "href-vars"		Resource Objects MUST have exactly one of the "href" and "href-vars"
	properties.		properties.
	In both forms, the links that "href" and "href-template" refer to are		In both forms, the links that "href" and "hrefTemplate" refer to are
	URI-references [RFC3986] whose base URI is that of the JSON Home		URI-references [RFC3986] whose base URI is that of the API Home
	Document itself.		Document itself.
	Resource Objects MAY also have a "hints" property, whose value is an		Resource Objects MAY also have a "hints" property, whose value is an
	object that uses named Resource Hints (see Section 4) as its		object that uses named Resource Hints (see Section 5) as its
	properties.		properties.
	3.1. Resolving Templated Links		4.1. Resolving Templated Links
	A URI can be derived from a Templated Link by treating the "href-		A URI can be derived from a Templated Link by treating the
	template" value as a Level 3 URI Template [RFC6570], using the "href-		"hrefTemplate" value as a Level 3 URI Template [RFC6570], using the
	vars" property to fill the template.		"hrefVars" property to fill the template.
	The "href-vars" property, in turn, is an object that acts as a		The "hrefVars" property, in turn, is an object that acts as a mapping
	mapping between variable names available to the template and absolute		between variable names available to the template and absolute URIs
	URIs that are used as global identifiers for the semantics and syntax		that are used as global identifiers for the semantics and syntax of
	of those variables.		those variables.
	For example, given the following Resource Object:		For example, given the following Resource Object:
	"http://example.org/rel/widget": {		"https://example.org/rel/widget": {
	"href-template": "/widgets/{widget_id}",		"hrefTemplate": "/widgets/{widget_id}",
	"href-vars": {		"hrefVars": {
	"widget_id": "http://example.org/param/widget"		"widget_id": "https://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+json"],		"acceptPatch": ["application/json-patch+json"],
	"accept-post": ["application/xml"],		"acceptRanges": ["bytes"]
	"accept-ranges": ["bytes"]
	}		}
	}		}
	If you understand that "http://example.org/param/widget" is an		If you understand that "https://example.org/param/widget" is an
	numeric identifier for a widget, you can then find the resource		numeric identifier for a widget, you can then find the resource
	corresponding to widget number 12345 at "http://example.org/		corresponding to widget number 12345 at "https://example.org/
	widgets/12345" (assuming that the Home Document is located at		widgets/12345" (assuming that the Home Document is located at
	"http://example.org/").		"https://example.org/").
	4. Resource Hints		5. 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 optimizing		interacting with a resource beforehand, as a means of optimizing
	communications, as well as advertising available behaviors (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 behavior 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).
	This specification defines a set of common hints, based upon		This specification defines a set of common hints, based upon
	information that's discoverable by directly interacting with		information that's discoverable by directly interacting with
	resources. See Section 9.1 for information on defining new hints.		resources. See Section 7.1 for information on defining new hints.
	4.1. allow		5.1. allow
	o Resource Hint Name: allow		o Resource Hint Name: allow
	o Description: Hints the HTTP methods that the current client will		o Description: Hints the HTTP methods that the current client will
	be able to use to interact with the resource; equivalent to the		be able to use to interact with the resource; equivalent to the
	Allow HTTP response header.		Allow HTTP response header.
	o Specification: [this document]		o Specification: [this document]
	Content MUST be an array of strings, containing HTTP methods.		Content MUST be an array of strings, containing HTTP methods.
	4.2. formats		5.2. formats
	o Resource Hint Name: formats		o Resource Hint Name: formats
	o Description: Hints the representation types that the resource		o Description: Hints the representation types that the resource
	produces and consumes, using the GET and PUT methods respectively,		produces and consumes, using the GET and PUT methods respectively,
	subject to the 'allow' hint.		subject to the 'allow' hint.
	o Specification: [this document]		o Specification: [this document]
	Content MUST be an object, whose keys are media types, and values are		Content MUST be an object, whose keys are media types, and values are
	objects containing Representation Hints (see Section 5).		objects, currently empty.
	4.3. accept-patch		5.3. acceptPatch
	o Resource Hint Name: accept-patch		o Resource Hint Name: accept-Patch
	o Description: Hints the PATCH [RFC5789] request formats accepted by		o Description: Hints the PATCH [RFC5789] request formats accepted by
	the resource for this client; equivalent to the Accept-Patch HTTP		the resource for this client; equivalent to the Accept-Patch HTTP
	response header.		response header.
	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		5.4. acceptPost
	o Resource Hint Name: accept-post		o Resource Hint Name: acceptPost
	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		5.5. acceptRanges
	o Resource Hint Name: accept-ranges		o Resource Hint Name: acceptRanges
	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 [RFC7233].		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.		(typically, "bytes").
	4.6. accept-prefer		5.6. acceptPrefer
	o Resource Hint Name: accept-prefer		o Resource Hint Name: acceptPrefer
	o Description: Hints the preferences [RFC7240] supported by the		o Description: Hints the preferences [RFC7240] supported by the
	resource. Note that, as per that specifications, a preference can		resource. Note that, as per that specifications, a preference can
	be ignored by the server.		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, containing preferences.
	4.7. docs		5.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		5.8. preconditionRequired
	o Resource Hint Name: precondition-req		o Resource Hint Name: preconditionRequired
	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
	[RFC7232], to avoid conflicts due to concurrent updates.		[RFC7232], to avoid conflicts due to 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		5.9. authSchemes
	o Resource Hint Name: auth-req		o Resource Hint Name: authSchemes
	o Description: Hints that the resource requires authentication using		o Description: Hints that the resource requires authentication using
	the HTTP Authentication Framework [RFC7235].		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:
	{		{
	"auth-req": [		"authSchemes": [
	{		{
	"scheme": "Basic",		"scheme": "Basic",
	"realms": ["private"]		"realms": ["private"]
	}		}
	]		]
	}		}
	4.10. status		5.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 404 (Not Found) or 410 (Gone) HTTP status code if
			accessed.
	5. Representation Hints
	TBD
	6. Creating and Serving Home Documents
	When making a home document available, there are a few things to keep
	in mind:
	o A home document is best located at a memorable URI, because its
	URI will effectively become the URI for the API itself to clients.
	o Home documents can be personalized, just as "normal" home pages
	can. For example, you might advertise different URIs, and/or
	different kinds of link relations, depending on the client's
	identity.
	o Home documents SHOULD be assigned a freshness lifetime (e.g.,
	"Cache-Control: max-age=3600") so that clients can cache them, to
	avoid having to fetch it every time the client interacts with the
	service.
	o Custom link relation types, as well as the URIs for variables,
	should lead to documentation for those constructs.
	6.1. Managing Change in Home Documents
	The URIs used in home documents MAY change over time. However,
	changing them can cause issues for clients that are relying on cached
	home documents containing old links.
	To mitigate the impact of such changes, servers SHOULD consider:
	o Reducing the freshness lifetime of home documents before a link
	change, so that clients are less likely to refer to an "old"
	document.
	o Regarding the "old" and "new" URIs as equally valid references for
	an "overlap" period.
	o After that period, handling requests for the "old" URIs
	appropriately; e.g., with a 404 Not Found, or by redirecting the
	client to the new URI.
	6.2. Evolving and Mixing APIs with Home Documents
	Using home documents affords the opportunity to change the "shape" of
	the API over time, without breaking old clients.
	This includes introducing new functions alongside the old ones - by
	adding new link relation types with corresponding resource objects -
	as well as adding new template variables, media types, and so on.
	It's important to realise that a home document can serve more than
	one "API" at a time; by listing all relevant relation types, it can
	effectively "mix" different APIs, allowing clients to work with
	different resources as they see fit.
	6.3. Documenting APIs that use Home Documents
	Another use case for "static" API description formats like WSDL and
	WADL is to generate documentation for the API from them.
	An API that uses the home document format correctly won't have a need
	to do so, provided that the link relation types and media types it
	uses are well-documented already.
	7. Consuming Home Documents
	Clients might use home documents in a variety of ways.
	In the most common case - actually consuming the API - the client
	will scan the Resources Object for the link relation(s) that it is
	interested in, and then to interact with the resource(s) referred to.
	Resource Hints can be used to optimize communication with the client,
	as well as to inform as to the permissible actions (e.g., whether PUT
	is likely to be supported).
	Note that the home document is a "living" document; it does not
	represent a "contract", but rather is expected to be inspected before
	each interaction. In particular, links from the home document MUST
	NOT be assumed to be valid beyond the freshness lifetime of the home
	document, as per HTTP's caching model [RFC7234].
	As a result, clients SHOULD cache the home document (as per
	[RFC7234]), to avoid fetching it before every interaction (which
	would otherwise be required).
	Likewise, a client encountering a 404 Not Found on a link SHOULD
	obtain a fresh copy of the home document, to assure that it is up-to-
	date.
	8. Security Considerations		6. 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
	for that server.		for that server.
	9. IANA Considerations		7. IANA Considerations
	9.1. HTTP Resource Hint Registry		7.1. HTTP Resource Hint Registry
	This specification defines the HTTP Resource Hint Registry. See		This specification defines the HTTP Resource Hint Registry. See
	Section 4 for a general description of the function of resource		Section 5 for a general description of the function of resource
	hints.		hints.
	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
	skipping to change at page 13, line 43 ¶		skipping to change at page 12, line 47 ¶
	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 5.
	9.2. HTTP Representation Hint Registry
	TBD
	9.3. Media Type Registration		7.2. Media Type Registration
	TBD		TBD
	10. References		8. References
	10.1. Normative References		8.1. Normative References
	[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,		Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/
	DOI 10.17487/RFC2119, March 1997,		RFC2119, March 1997,
	<http://www.rfc-editor.org/info/rfc2119>.		<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
	RFC 3986, DOI 10.17487/RFC3986, January 2005,		3986, DOI 10.17487/RFC3986, January 2005,
	<http://www.rfc-editor.org/info/rfc3986>.		<http://www.rfc-editor.org/info/rfc3986>.
	[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,
	DOI 10.17487/RFC5226, May 2008,		DOI 10.17487/RFC5226, May 2008,
	<http://www.rfc-editor.org/info/rfc5226>.		<http://www.rfc-editor.org/info/rfc5226>.
	[RFC5988] Nottingham, M., "Web Linking", RFC 5988,		[RFC5988] Nottingham, M., "Web Linking", RFC 5988, DOI 10.17487/
	DOI 10.17487/RFC5988, October 2010,		RFC5988, October 2010,
	<http://www.rfc-editor.org/info/rfc5988>.		<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,		and D. Orchard, "URI Template", RFC 6570, DOI 10.17487/
	DOI 10.17487/RFC6570, March 2012,		RFC6570, March 2012,
	<http://www.rfc-editor.org/info/rfc6570>.		<http://www.rfc-editor.org/info/rfc6570>.
	[RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data		[RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
	Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March		Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March
	2014, <http://www.rfc-editor.org/info/rfc7159>.		2014, <http://www.rfc-editor.org/info/rfc7159>.
	[RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,		[RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
	Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching",		Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching",
	RFC 7234, DOI 10.17487/RFC7234, June 2014,		RFC 7234, DOI 10.17487/RFC7234, June 2014,
	<http://www.rfc-editor.org/info/rfc7234>.		<http://www.rfc-editor.org/info/rfc7234>.
	10.2. Informative References		8.2. Informative References
	[MICROFORMATS]
	microformats.org, "Microformats", n.d.,
	<http://microformats.org/>.
	[RFC4151] Kindberg, T. and S. Hawke, "The 'tag' URI Scheme",		[RFC4151] Kindberg, T. and S. Hawke, "The 'tag' URI Scheme", RFC
	RFC 4151, DOI 10.17487/RFC4151, October 2005,		4151, DOI 10.17487/RFC4151, October 2005,
	<http://www.rfc-editor.org/info/rfc4151>.		<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
	RFC 5789, DOI 10.17487/RFC5789, March 2010,		5789, DOI 10.17487/RFC5789, March 2010,
	<http://www.rfc-editor.org/info/rfc5789>.		<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
	RFC 6838, DOI 10.17487/RFC6838, January 2013,		6838, DOI 10.17487/RFC6838, January 2013,
	<http://www.rfc-editor.org/info/rfc6838>.		<http://www.rfc-editor.org/info/rfc6838>.
	[RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer		[RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
	Protocol (HTTP/1.1): Message Syntax and Routing",		Protocol (HTTP/1.1): Message Syntax and Routing", RFC
	RFC 7230, DOI 10.17487/RFC7230, June 2014,		7230, DOI 10.17487/RFC7230, June 2014,
	<http://www.rfc-editor.org/info/rfc7230>.		<http://www.rfc-editor.org/info/rfc7230>.
	[RFC7232] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer		[RFC7232] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
	Protocol (HTTP/1.1): Conditional Requests", RFC 7232,		Protocol (HTTP/1.1): Conditional Requests", RFC 7232, DOI
	DOI 10.17487/RFC7232, June 2014,		10.17487/RFC7232, June 2014,
	<http://www.rfc-editor.org/info/rfc7232>.		<http://www.rfc-editor.org/info/rfc7232>.
	[RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed.,		[RFC7233] Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed.,
	"Hypertext Transfer Protocol (HTTP/1.1): Range Requests",		"Hypertext Transfer Protocol (HTTP/1.1): Range Requests",
	RFC 7233, DOI 10.17487/RFC7233, June 2014,		RFC 7233, DOI 10.17487/RFC7233, June 2014,
	<http://www.rfc-editor.org/info/rfc7233>.		<http://www.rfc-editor.org/info/rfc7233>.
	[RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer		[RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
	Protocol (HTTP/1.1): Authentication", RFC 7235,		Protocol (HTTP/1.1): Authentication", RFC 7235, DOI
	DOI 10.17487/RFC7235, June 2014,		10.17487/RFC7235, June 2014,
	<http://www.rfc-editor.org/info/rfc7235>.		<http://www.rfc-editor.org/info/rfc7235>.
	[RFC7240] Snell, J., "Prefer Header for HTTP", RFC 7240,		[RFC7240] Snell, J., "Prefer Header for HTTP", RFC 7240, DOI
	DOI 10.17487/RFC7240, June 2014,		10.17487/RFC7240, June 2014,
	<http://www.rfc-editor.org/info/rfc7240>.		<http://www.rfc-editor.org/info/rfc7240>.
	[WADL] Hadley, M. and Sun Microsystems, "Web Application
	Description Language", n.d.,
	<http://www.w3.org/Submission/wadl/>.
	Appendix A. Acknowledgements		Appendix A. Acknowledgements
	Thanks to Jan Algermissen, Mike Amundsen, Bill Burke, Sven Dietze,		Thanks to Jan Algermissen, Mike Amundsen, Bill Burke, Sven Dietze,
	Graham Klyne, Leif Hedstrom, Joe Hildebrand, Jeni Tennison, Erik		Graham Klyne, Leif Hedstrom, Joe Hildebrand, Jeni Tennison, Erik
	Wilde and Jorge Williams for their suggestions and feedback.		Wilde and Jorge Williams for their suggestions and feedback.
	Appendix B. Frequently Asked Questions		Appendix B. Considerations for Creating and Serving Home Documents
	B.1. Why not Microformats?		When making an API home document available, there are a few things to
			keep in mind:
	Browser-centric Web applications use HTML as their representation		o A home document is best located at a memorable URI, because its
	format of choice. While it is possible to augment HTML for non-		URI will effectively become the URI for the API itself to clients.
	browser clients (using techniques like Microformats [MICROFORMATS]),
	a few issues become evident when doing so:
	o HTML has a very forgiving syntax. While this is appropriate for		o Home documents can be personalized, just as "normal" home pages
	browsers (especially considering that there are many million HTML		can. For example, you might advertise different URIs, and/or
	authors in the world), it makes for a less-than-precise language		different kinds of link relations, depending on the client's
	for machines, resulting in both overhead (parsing and		identity.
	transmission) as well as lack of precision.
	o HTML is presentation-centric, making it tempting to reformat it		o Home documents ought to be assigned a freshness lifetime (e.g.,
	from time to time, to improve the "look and feel" of a page.		"Cache-Control: max-age=3600") so that clients can cache them, to
	However, doing so can cause comparatively brittle non-browser		avoid having to fetch it every time the client interacts with the
	clients to lose their understanding of the content's semantics,		service.
	unless very careful controls are in place.
	Because of this, it's most practical to define a separate format, and		o Custom link relation types, as well as the URIs for variables,
	JSON is easily machine-readable, precise, and has a better chance of		should lead to documentation for those constructs.
	being managed for stability.
	B.2. Why doesn't the format allow references or inheritance?		B.1. Managing Change in Home Documents
			The URIs used in API home documents MAY change over time. However,
			changing them can cause issues for clients that are relying on cached
			home documents containing old links.
			To mitigate the impact of such changes, servers ought to consider:
			o Reducing the freshness lifetime of home documents before a link
			change, so that clients are less likely to refer to an "old"
			document.
			o Regarding the "old" and "new" URIs as equally valid references for
			an "overlap" period.
			o After that period, handling requests for the "old" URIs
			appropriately; e.g., with a 404 Not Found, or by redirecting the
			client to the new URI.
			B.2. Evolving and Mixing APIs with Home Documents
			Using home documents affords the opportunity to change the "shape" of
			the API over time, without breaking old clients.
			This includes introducing new functions alongside the old ones - by
			adding new link relation types with corresponding resource objects -
			as well as adding new template variables, media types, and so on.
			It's important to realise that a home document can serve more than
			one "API" at a time; by listing all relevant relation types, it can
			effectively "mix" different APIs, allowing clients to work with
			different resources as they see fit.
			Appendix C. Considerations for Consuming Home Documents
			Clients might use home documents in a variety of ways.
			In the most common case - actually consuming the API - the client
			will scan the Resources Object for the link relation(s) that it is
			interested in, and then to interact with the resource(s) referred to.
			Resource Hints can be used to optimize communication with the client,
			as well as to inform as to the permissible actions (e.g., whether PUT
			is likely to be supported).
			Note that the home document is a "living" document; it does not
			represent a "contract", but rather is expected to be inspected before
			each interaction. In particular, links from the home document MUST
			NOT be assumed to be valid beyond the freshness lifetime of the home
			document, as per HTTP's caching model [RFC7234].
			As a result, clients ought to cache the home document (as per
			[RFC7234]), to avoid fetching it before every interaction (which
			would otherwise be required).
			Likewise, a client encountering a 404 Not Found on a link is
			encouraged obtain a fresh copy of the home document, to assure that
			it is up-to-date.
			Appendix D. Frequently Asked Questions
			D.1. Why doesn't the format allow references or inheritance?
	Adding inheritance or references would allow more modularity in the		Adding inheritance or references would allow more modularity in the
	format and make it more compact, at the cost of considerable		format and make it more compact, at the cost of considerable
	complexity and the associated potential for errors (both in the		complexity and the associated potential for errors (both in the
	specification and by its users).		specification and by its users).
	Since good tools and compression are effective ways to achieve the		Since good tools and compression are effective ways to achieve the
	same ends, this specification doesn't attempt them.		same ends, this specification doesn't attempt them.
	B.3. What about authentication?		D.2. What about "Faults" (i.e., errors)?
	In HTTP, authentication is discoverable by interacting with the
	resource (usually, by getting a 401 Unauthorized response status
	code, along with one or more challenges). While the home document
	could hint it, this isn't yet done, to avoid possible security
	complications.
	B.4. What about "Faults" (i.e., errors)?
	In HTTP, errors are conveyed by HTTP status codes. While this		In HTTP, errors are conveyed by HTTP status codes. While this
	specification could (and even may) allow enumeration of possible		specification could (and even may) allow enumeration of possible
	error conditions, there's a concern that this will encourage		error conditions, there's a concern that this will encourage
	applications to define many such "faults", leading to tight coupling		applications to define many such "faults", leading to tight coupling
	between the application and its clients.		between the application and its clients.
	B.5. How Do I find the schema for a format?		D.3. How Do I find the schema for a format?
	That isn't addressed by home documents. Ultimately, it's up to the		That isn't addressed by home documents. Ultimately, it's up to the
	media type accepted and generated by resources to define and		media type accepted and generated by resources to define and
	constrain (or not) their syntax.		constrain (or not) their syntax.
	B.6. How do I express complex query arguments?		D.4. How do I express complex query arguments?
	Complex queries - i.e., those that exceed the expressive power of		Complex queries - i.e., those that exceed the expressive power of
	Link Templates or would require ambiguous properties of a "resources"		Link Templates or would require ambiguous properties of a "resources"
	object - aren't intended to be defined by a home document. The		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		appropriate way to do this is with a "form" language, much as HTML
	defines.		defines.
	Note that it is possible to support multiple query syntaxes on the		Note that it is possible to support multiple query syntaxes on the
	same base URL, using more than one link relation type; see the		same base URL, using more than one link relation type; see the
	example at the start of the document.		example at the start of the document.
	Appendix C. Open Issues
	The following is a list of placeholders for open issues.
	o top-level object(s)
	* contact details
	* overall documentation
	* release info?
	* ToS
	* rate limiting (per-resource?)
	o Resource Hints
	* indicate a POST to 201 Created pattern
	* indicate an "action" POST
	* outbound links
	* forms?
	o Representation Hints
	* format profiles
	* deprecation
	o Defining new top-level and resource object properties - how new
	ones are minted, registry, etc.
	o Discovery (e.g., conneg, .well-known, etc.)
	o LIMITED include function?
	Author's Address		Author's Address
	Mark Nottingham		Mark Nottingham
	Email: mnot@mnot.net		Email: mnot@mnot.net
	URI: http://www.mnot.net/		URI: https://www.mnot.net/
End of changes. 91 change blocks.
	345 lines changed or deleted		310 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/