< draft-nottingham-json-home-02.txt		draft-nottingham-json-home-03.txt >
	Network Working Group M. Nottingham		Network Working Group M. Nottingham
	Internet-Draft September 13, 2012		Internet-Draft May 8, 2013
	Intended status: Informational		Intended status: Informational
	Expires: March 17, 2013		Expires: November 9, 2013
	Home Documents for HTTP APIs		Home Documents for HTTP APIs
	draft-nottingham-json-home-02		draft-nottingham-json-home-03
	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 [1].		This draft should be discussed on the apps-discuss mailing list; see
			[apps-discuss].
	Status of this Memo		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 March 17, 2013.		This Internet-Draft will expire on November 9, 2013.
	Copyright Notice		Copyright Notice
	Copyright (c) 2012 IETF Trust and the persons identified as the		Copyright (c) 2013 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
	2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 3		1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3
	3. JSON Home Documents . . . . . . . . . . . . . . . . . . . . . 3		2. JSON Home Documents . . . . . . . . . . . . . . . . . . . . . 3
	4. Resource Objects . . . . . . . . . . . . . . . . . . . . . . . 5		3. Resource Objects . . . . . . . . . . . . . . . . . . . . . . . 5
	4.1. Resolving Templated Links . . . . . . . . . . . . . . . . 5		3.1. Resolving Templated Links . . . . . . . . . . . . . . . . 6
	5. Resource Hints . . . . . . . . . . . . . . . . . . . . . . . . 6		4. Resource Hints . . . . . . . . . . . . . . . . . . . . . . . . 6
	5.1. allow . . . . . . . . . . . . . . . . . . . . . . . . . . 7		4.1. allow . . . . . . . . . . . . . . . . . . . . . . . . . . 7
	5.2. representations . . . . . . . . . . . . . . . . . . . . . 7		4.2. formats . . . . . . . . . . . . . . . . . . . . . . . . . 7
	5.3. accept-patch . . . . . . . . . . . . . . . . . . . . . . . 7		4.3. accept-patch . . . . . . . . . . . . . . . . . . . . . . . 7
	5.4. accept-post . . . . . . . . . . . . . . . . . . . . . . . 7		4.4. accept-post . . . . . . . . . . . . . . . . . . . . . . . 8
	5.5. accept-put . . . . . . . . . . . . . . . . . . . . . . . . 7		4.5. accept-ranges . . . . . . . . . . . . . . . . . . . . . . 8
	5.6. accept-ranges . . . . . . . . . . . . . . . . . . . . . . 8		4.6. accept-prefer . . . . . . . . . . . . . . . . . . . . . . 8
	5.7. prefer . . . . . . . . . . . . . . . . . . . . . . . . . . 8		4.7. docs . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
	5.8. docs . . . . . . . . . . . . . . . . . . . . . . . . . . . 8		4.8. precondition-req . . . . . . . . . . . . . . . . . . . . . 9
	5.9. precondition-req . . . . . . . . . . . . . . . . . . . . . 8		4.9. auth-req . . . . . . . . . . . . . . . . . . . . . . . . . 9
	5.10. auth-req . . . . . . . . . . . . . . . . . . . . . . . . . 8		4.10. status . . . . . . . . . . . . . . . . . . . . . . . . . . 9
	5.11. status . . . . . . . . . . . . . . . . . . . . . . . . . . 9		5. Representation Hints . . . . . . . . . . . . . . . . . . . . . 10
	6. Creating and Serving Home Documents . . . . . . . . . . . . . 9		6. Creating and Serving Home Documents . . . . . . . . . . . . . 10
	6.1. Managing Change in Home Documents . . . . . . . . . . . . 9		6.1. Managing Change in Home Documents . . . . . . . . . . . . 10
	6.2. Evolving and Mixing APIs with Home Documents . . . . . . . 10		6.2. Evolving and Mixing APIs with Home Documents . . . . . . . 11
	6.3. Documenting APIs that use Home Documents . . . . . . . . . 10		6.3. Documenting APIs that use Home Documents . . . . . . . . . 11
	7. Consuming Home Documents . . . . . . . . . . . . . . . . . . . 10		7. Consuming Home Documents . . . . . . . . . . . . . . . . . . . 11
	8. Security Considerations . . . . . . . . . . . . . . . . . . . 11		8. Security Considerations . . . . . . . . . . . . . . . . . . . 12
	9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11		9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12
	10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11		9.1. HTTP Resource Hint Registry . . . . . . . . . . . . . . . 12
	10.1. Normative References . . . . . . . . . . . . . . . . . . . 11		9.2. HTTP Representation Hint Registry . . . . . . . . . . . . 12
	10.2. Informative References . . . . . . . . . . . . . . . . . . 12		9.3. Media Type Registration . . . . . . . . . . . . . . . . . 12
	Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 12		10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13
	Appendix B. Frequently Asked Questions . . . . . . . . . . . . . 13		10.1. Normative References . . . . . . . . . . . . . . . . . . . 13
	B.1. Why not Microformats? . . . . . . . . . . . . . . . . . . 13		10.2. Informative References . . . . . . . . . . . . . . . . . . 13
	B.2. What about authentication? . . . . . . . . . . . . . . . . 13		Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 14
	B.3. What about 'Faults' (i.e., errors)? . . . . . . . . . . . 13		Appendix B. Frequently Asked Questions . . . . . . . . . . . . . 14
	B.4. How Do I find the XML Schema / JSON Schema / etc. for		B.1. Why not Microformats? . . . . . . . . . . . . . . . . . . 14
	a particular media type? . . . . . . . . . . . . . . . . . 13		B.2. Why doesn't the format allow references or inheritance? . 15
	B.5. How do I express complex query arguments? . . . . . . . . 14		B.3. What about authentication? . . . . . . . . . . . . . . . . 15
	Appendix C. Open Issues . . . . . . . . . . . . . . . . . . . . . 14		B.4. What about "Faults" (i.e., errors)? . . . . . . . . . . . 15
	Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 14		B.5. How Do I find the schema for a format? . . . . . . . . . . 15
			B.6. How do I express complex query arguments? . . . . . . . . 15
			Appendix C. Open Issues . . . . . . . . . . . . . . . . . . . . . 16
			Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 16
	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
	"http://api.example.com/v1.0/widgets/abc123/properties") have		"http://api.example.com/v1.0/widgets/abc123/properties"), which have
	resulted in brittle, tight coupling between clients and servers.		resulted in brittle, tight coupling between clients and servers.
	Sometimes, these APIs were documented by a document format like		Sometimes, these APIs are documented by a document format like [WADL]
	WADL [2] that is used as a design time description; i.e., the URIs		that is used as a design-time description; i.e., the URIs and other
	and other information they describe are "baked into" client		information they describe are "baked into" client implementations.
	implementations.
	In contrast, a "follow your nose" API advertises the resources		In contrast, a "follow your nose" API advertises the resources
	available to clients using link relations [RFC5988] and the formats		available to clients using link relations [RFC5988] and the formats
	they support using internet media types [RFC4288]. A client can then		they support using internet media types [RFC6838]. A client can then
	decide - at run time - which resources to interact with based upon		decide - at run time - which resources to interact with based upon
	its capabilities (as described by link relations), and the server can		its capabilities (as described by link relations), and the server can
	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, the client needs to be able to discover this information		As such, clients need to be able to discover this information quickly
	quickly and efficiently use it to interact with the server. Just as		and efficiently use it to interact with the server. Just as with a
	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 the JSON format
	[RFC4627].		[RFC4627].
	2. Requirements		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].
	3. 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 [RFC4627] 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, an		Its content consists of a root object with a "resources" property,
	object whose 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": {		"http://example.org/rel/widgets": {
	"href": "/widgets/"		"href": "/widgets/"
	},
	"http://example.org/rel/widget": {
	"href-template": "/widgets/{widget_id}",
	"href-vars": {
	"widget_id": "http://example.org/param/widget"
	},		},
	"hints": {		"http://example.org/rel/widget": {
	"allow": ["GET", "PUT", "DELETE", "PATCH"],		"href-template": "/widgets/{widget_id}",
	"representations": ["application/json"],		"href-vars": {
	"accept-patch": ["application/json-patch"],		"widget_id": "http://example.org/param/widget"
	"accept-post": ["application/xml"],		},
	"accept-ranges": ["bytes"]		"hints": {
			"allow": ["GET", "PUT", "DELETE", "PATCH"],
			"formats": {
			"application/json": {}
			},
			"accept-patch": ["application/json-patch"],
			"accept-post": ["application/xml"],
			"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 "http://example.org/rel/widgets". It also links to
	an undefined number of resources with the relation type		an unknown number of resources with the relation type
	"http://example.org/rel/widget" using a URI Template [RFC6570], along		"http://example.org/rel/widget" using a URI Template [RFC6570], along
	with a mapping of several identifiers to specific variables for use		with a mapping of identifiers to a variable for use in that template.
	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 [I-D.ietf-httpbis-p5-range] 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.
	Note that the properties of a "resources" object MUST be unique;		Effectively, this names a set of behaviors, as described by a
	i.e., one Resource Object per relation type.		resource object, with a link relation type. This means that several
			link relations might apply to a common base URL; e.g.:
	4. Resource Objects		{
			"resources": {
			"http://example.org/rel/search-by-id": {
			"href-template": "/search?id={widget}",
			"href-vars": {
			"widget_name": "http://example.org/param/widget"
			}
			},
			"http://example.org/rel/search-by-name": {
			"href-template": "/search?name={widget_name}",
			"href-vars": {
			"widget_name": "http://example.org/param/widget_name"
			}
			}
			}
			}
			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.
	Resource Objects MUST have only and exactly one of the "href" and
	"href-template" properties.
	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 "href-template" property, whose
	value is a URI Template [RFC6570]. When "href-template" is present,		value is a URI Template [RFC6570]. When "href-template" is present,
	the Resource Object MUST have a "href-vars" property; see "Resolving		the Resource Object MUST have a "href-vars" property; see "Resolving
	Templated Links".		Templated Links".
			Resource Objects MUST have exactly one of the "href" and "href-vars"
			properties.
	In both forms, the links that "href" and "href-template" refer to are		In both forms, the links that "href" and "href-template" 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 JSON 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 as its properties.		object that uses named Resource Hints (see Section 4) as its
			properties.
	4.1. Resolving Templated Links		3.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 "href-
	template" value as a Level 3 URI Template [RFC6570], using the "href-		template" value as a Level 3 URI Template [RFC6570], using the "href-
	vars" property to fill the template.		vars" property to fill the template.
	The "href-vars" property, in turn, is an object that acts as a		The "href-vars" property, in turn, is an object that acts as a
	mapping between variable names available to the template and absolute		mapping between variable names available to the template and absolute
	URIs that are used as global identifiers for the semantics and syntax		URIs that are used as global identifiers for the semantics and syntax
	of those variables.		of those variables.
	For example, given the following Resource Object:		For example, given the following Resource Object:
	"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"],
	"representations": ["application/json"],		"formats": {
	"accept-patch": ["application/json-patch"],		"application/json": {}
	"accept-post": ["application/xml"],		},
	"accept-ranges": ["bytes"]		"accept-patch": ["application/json-patch"],
			"accept-post": ["application/xml"],
			"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 (perhaps by dereferencing that URL
	and reading the documentation), you can then find the resource		and reading the documentation), you can then find the resource
	corresponding to widget number 12345 at		corresponding to widget number 12345 at
	"http://example.org/widgets/12345" (assuming that the Home Document		"http://example.org/widgets/12345" (assuming that the Home Document
	is located at "http://example.org/").		is located at "http://example.org/").
	5. 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 optimising
	communications, as well as advertising available behaviours (e.g., to		communications, as well as advertising available behaviours (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 behaviour 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
	could 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).		it (such as a "widgets" collection) or describing it (e.g., one
			linked to it with a "describedby" link relation).
	This specification defines a set of common hints, based upon		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. A future draft will explain how to define new hints.		resources. See Section 9.1 for information on defining new hints.
	5.1. allow		4.1. allow
	Hints the HTTP methods that the current client will be able to use to		o Resource Hint Name: allow
	interact with the resource; equivalent to the Allow HTTP response		o Description: Hints the HTTP methods that the current client will
	header.		be able to use to interact with the resource; equivalent to the
			Allow HTTP response header.
			o Specification: [this document]
	Content MUST be an array of strings, containing HTTP methods.		Content MUST be an array of strings, containing HTTP methods.
	5.2. representations		4.2. formats
	Hints the representation types that the resource produces and		o Resource Hint Name: formats
	consumes, using the GET and PUT methods respectively, subject to the		o Description: Hints the representation types that the resource
	'allow' hint.		produces and consumes, using the GET and PUT methods respectively,
			subject to the 'allow' hint.
			o Specification: [this document]
	Content MUST be an array of strings, containing media types.		Content MUST be an object, whose keys are media types, and values are
			objects containing Representation Hints (see Section 5).
	5.3. accept-patch		4.3. accept-patch
	Hints the PATCH request formats [RFC5789] accepted by the resource		o Resource Hint Name: accept-patch
	for this client; equivalent to the Accept-Patch HTTP response header.		o Description: Hints the PATCH [RFC5789] request formats accepted by
			the resource for this client; equivalent to the Accept-Patch HTTP
			response header.
			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.
	5.4. accept-post		4.4. accept-post
	Hints the POST request formats accepted by the resource for this		o Resource Hint Name: accept-post
	client.		o Description: Hints the POST request formats accepted by the
			resource for this client.
			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.
	5.5. accept-put		4.5. accept-ranges
	Hints the PUT request formats accepted by the resource for this
	client.
	Content MUST be an array of strings, containing media types. If
	absent, a client MAY assume that any format indicated by the
	'representations' hint is acceptable in a PUT.
	When this hint is present, "PUT" SHOULD be listed in the "allow"
	hint.
	5.6. accept-ranges
	Hints the range-specifiers available to the client for this resource;		o Resource Hint Name: accept-ranges
	equivalent to the Accept-Ranges HTTP response header		o Description: Hints the range-specifiers available to the client
	[I-D.ietf-httpbis-p5-range].		for this resource; equivalent to the Accept-Ranges HTTP response
			header [I-D.ietf-httpbis-p5-range].
			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.
	5.7. prefer		4.6. accept-prefer
	Hints the preferences [I-D.snell-http-prefer] supported by the		o Resource Hint Name: accept-prefer
	resource. Note that, as per that specifications, a preference can be		o Description: Hints the preferences [I-D.snell-http-prefer]
	ignored by the server.		supported by the resource. Note that, as per that specifications,
			a preference can be ignored by the server.
			o Specification: [this document]
	Content MUST be an array of strings, contain preferences.		Content MUST be an array of strings, contain preferences.
	5.8. docs		4.7. docs
	Hints the location for human-readable documentation for the relation		o Resource Hint Name: docs
	type of the resource.		o Description: Hints the location for human-readable documentation
			for the relation type of the resource.
			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.
	5.9. precondition-req		4.8. precondition-req
	Hints that the resource requires state-changing requests (e.g., PUT,		o Resource Hint Name: precondition-req
	PATCH) to include a precondition, as per		o Description: Hints that the resource requires state-changing
	[I-D.ietf-httpbis-p4-conditional], to avoid conflicts due to		requests (e.g., PUT, PATCH) to include a precondition, as per
	concurrent updates.		[I-D.ietf-httpbis-p4-conditional], to avoid conflicts due to
			concurrent updates.
			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.
	5.10. auth-req		4.9. auth-req
	Hints that the resource requires authentication using the HTTP		o Resource Hint Name: auth-req
	Authentication Framework [I-D.ietf-httpbis-p7-auth].		o Description: Hints that the resource requires authentication using
			the HTTP Authentication Framework [I-D.ietf-httpbis-p7-auth].
			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": [		"auth-req": [
	{		{
	"scheme": "Basic",		"scheme": "Basic",
	"realms": ["private"]		"realms": ["private"]
	}		}
	]		]
	}		}
	5.11. status		4.10. status
	Hints the status of the resource.		o Resource Hint Name: status
			o Description: Hints the status of the resource.
			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
			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 personalised, 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
	skipping to change at page 9, line 49 ¶		skipping to change at page 10, line 38 ¶
	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 these risks, servers changing links SHOULD consider:		To mitigate the impact of such changes, servers SHOULD consider:
	o Reducing the freshness lifetime of home documents before a link		o Reducing the freshness lifetime of home documents before a link
	change, so that clients are less likely to refer to an "old"		change, so that clients are less likely to refer to an "old"
	document		document.
	o Assure that they handle requests for the "old" URIs appropriately;		o Regarding the "old" and "new" URIs as equally valid references for
	e.g., with a 404 Not Found, or by redirecting the client to the		an "overlap" period.
	new URI.		o After that period, handling requests for the "old" URIs
	o Alternatively, considering the "old" and "new" URIs as equally		appropriately; e.g., with a 404 Not Found, or by redirecting the
	valid references for an "overlap" period.		client to the new URI.
	Generally, servers ought not to change URIs without good cause.
	6.2. Evolving and Mixing APIs with Home Documents		6.2. Evolving and Mixing APIs with Home Documents
	Using home documents affords the opportunity to change the "shape" of		Using home documents affords the opportunity to change the "shape" of
	the API over time, without breaking old clients.		the API over time, without breaking old clients.
	This includes introducing new functions alongside the old ones - by		This includes introducing new functions alongside the old ones - by
	adding new link relation types with corresponding resource objects -		adding new link relation types with corresponding resource objects -
	as well as adding new template variables, media types, and so on.		as well as adding new template variables, media types, and so on.
	skipping to change at page 11, line 18 ¶		skipping to change at page 12, line 7 ¶
	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		[I-D.ietf-httpbis-p6-cache]), to avoid fetching it before every
	interaction (which would otherwise be required).		interaction (which 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
	TBD
	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		9. IANA Considerations
			9.1. HTTP Resource Hint Registry
			This specification defines the HTTP Resource Hint Registry. See
			Section 4 for a general description of the function of resource
			hints.
			In particular, resource hints are generic; that is, they are
			potentially applicable to any resource, not specific to one
			application of HTTP, nor to one particular format. Generally, they
			ought to be information that would otherwise be discoverable by
			interacting with the resource.
			Hint names MUST be composed of the lowercase letters (a-z), digits
			(0-9), underscores ("_") and hyphens ("-"), and MUST begin with a
			lowercase letter.
			Hint content SHOULD be described in terms of JSON [RFC4627]
			constructs.
			New hints are registered using the Expert Review process described in
			[RFC5226] to enforce the criteria above. Requests for registration
			of new resource hints are to use the following template:
			o Resource Hint Name: [hint name]
			o Description: [a short description of the hint's semantics]
			o Specification: [reference to specification document]
			Initial registrations are enumerated in Section 4.
			9.2. HTTP Representation Hint Registry
			TBD
			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]		[I-D.ietf-httpbis-p6-cache]
	Fielding, R., Lafon, Y., Nottingham, M., and J. Reschke,		Fielding, R., Nottingham, M., and J. Reschke, "Hypertext
	"HTTP/1.1, part 6: Caching",		Transfer Protocol (HTTP/1.1): Caching",
	draft-ietf-httpbis-p6-cache-19 (work in progress),		draft-ietf-httpbis-p6-cache-22 (work in progress),
	March 2012.		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, March 1997.
	[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, January 2005.
	[RFC4627] Crockford, D., "The application/json Media Type for		[RFC4627] Crockford, D., "The application/json Media Type for
	JavaScript Object Notation (JSON)", RFC 4627, July 2006.		JavaScript Object Notation (JSON)", RFC 4627, July 2006.
			[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
			IANA Considerations Section in RFCs", BCP 26, RFC 5226,
			May 2008.
	[RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010.		[RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010.
	[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, March 2012.
	10.2. Informative References		10.2. Informative References
	[I-D.ietf-httpbis-p4-conditional]		[I-D.ietf-httpbis-p4-conditional]
	Fielding, R., Lafon, Y., and J. Reschke, "HTTP/1.1, part		Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
	4: Conditional Requests",		(HTTP/1.1): Conditional Requests",
	draft-ietf-httpbis-p4-conditional-19 (work in progress),		draft-ietf-httpbis-p4-conditional-22 (work in progress),
	March 2012.		February 2013.
	[I-D.ietf-httpbis-p5-range]		[I-D.ietf-httpbis-p5-range]
	Fielding, R., Lafon, Y., and J. Reschke, "HTTP/1.1, part		Fielding, R., Lafon, Y., and J. Reschke, "Hypertext
	5: Range Requests and Partial Responses",		Transfer Protocol (HTTP/1.1): Range Requests",
	draft-ietf-httpbis-p5-range-19 (work in progress),		draft-ietf-httpbis-p5-range-22 (work in progress),
	March 2012.		February 2013.
	[I-D.ietf-httpbis-p7-auth]		[I-D.ietf-httpbis-p7-auth]
	Fielding, R., Lafon, Y., and J. Reschke, "HTTP/1.1, part		Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
	7: Authentication", draft-ietf-httpbis-p7-auth-19 (work in		(HTTP/1.1): Authentication", draft-ietf-httpbis-p7-auth-22
	progress), March 2012.		(work in progress), February 2013.
	[I-D.snell-http-prefer]		[I-D.snell-http-prefer]
	Snell, J., "Prefer Header for HTTP",		Snell, J., "Prefer Header for HTTP",
	draft-snell-http-prefer-12 (work in progress),		draft-snell-http-prefer-18 (work in progress),
	February 2012.		January 2013.
	[RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and		[MICROFORMATS]
	Registration Procedures", BCP 13, RFC 4288, December 2005.		microformats.org, "Microformats",
			<http://microformats.org/>.
	[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, March 2010.
	URIs		[RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type
			Specifications and Registration Procedures", BCP 13,
	[1] <https://www.ietf.org/mailman/listinfo/apps-discuss>		RFC 6838, January 2013.
	[2] <http://www.w3.org/Submission/wadl/>		[WADL] Hadley, M. and Sun Microsystems, "Web Application
			Description Language",
			<http://www.w3.org/Submission/wadl/>.
	[3] <http://microformats.org/>		[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, Graham Klyne,
	Leif Hedstrom, Jeni Tennison and Jorge Williams for their suggestions		Leif Hedstrom, Jeni Tennison, Erik Wilde and Jorge Williams for their
	and feedback.		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 [3] ), a few		browser clients (using techniques like Microformats [MICROFORMATS]),
	issues become evident when doing so:		a few issues become evident when doing so:
	o HTML has a very forgiving syntax. While this is appropriate for		o HTML has a very forgiving syntax. While this is appropriate for
	browsers (especially considering that there are many million HTML		browsers (especially considering that there are many million HTML
	authors in the world), it makes for a less-than-precise language		authors in the world), it makes for a less-than-precise language
	for machines, resulting in both overhead (parsing and		for machines, resulting in both overhead (parsing and
	transmission) as well as lack of precision.		transmission) as well as lack of precision.
	o HTML is presentation-centric, making it tempting to reformat it		o HTML is presentation-centric, making it tempting to reformat it
	from time to time, to improve the "look and feel" of a page.		from time to time, to improve the "look and feel" of a page.
	However, doing so can cause comparatively brittle non-browser		However, doing so can cause comparatively brittle non-browser
	clients to lose their understanding of the content's semantics,		clients to lose their understanding of the content's semantics,
	unless very careful controls are in place.		unless very careful controls are in place.
	Because of this, it's most practical to define a separate format, and		Because of this, it's most practical to define a separate format, and
	JSON is easily machine-readable, precise, and has a better chance of		JSON is easily machine-readable, precise, and has a better chance of
	being managed for stability.		being managed for stability.
	B.2. What about authentication?		B.2. Why doesn't the format allow references or inheritance?
			Adding inheritance or references would allow more modularity in the
			format and make it more compact, at the cost of considerable
			complexity and the associated potential for errors (both in the
			specification and by its users).
			Since good tools and compression are effective ways to achieve the
			same ends, this specification doesn't attempt them.
			B.3. What about authentication?
	In HTTP, authentication is discoverable by interacting with the		In HTTP, authentication is discoverable by interacting with the
	resource (usually, by getting a 401 Unauthorized response status		resource (usually, by getting a 401 Unauthorized response status
	code, along with one or more challenges). While the home document		code, along with one or more challenges). While the home document
	could hint it, this isn't yet done, to avoid possible security		could hint it, this isn't yet done, to avoid possible security
	complications.		complications.
	B.3. What about 'Faults' (i.e., errors)?		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.
	So, this is an area of possible future development; if any such		B.5. How Do I find the schema for a format?
	mechanism appears here, it's likely to be quite restricted.
	B.4. How Do I find the XML Schema / JSON Schema / etc. for a particular
	media type?
	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.5. How do I express complex query arguments?		B.6. 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.
	Future revisions of this specification may define or accommodate the		Note that it is possible to support multiple query syntaxes on the
	use of such a form in the home document.		same base URL, using more than one link relation type; see the
			example at the start of the document.
	Appendix C. Open Issues		Appendix C. Open Issues
	The following is a list of placeholders for open issues.		The following is a list of placeholders for open issues.
	o Refining and extending representation formats - "application/xml",		o top-level object(s)
	for example, isn't enough. While a media type for every		* contact details
	representation is one answer, something like 'profile' might be		* overall documentation
	good too.		* release info?
	o Object for contact details - do we need an object that describes		* ToS
	who's running the API, etc?		* rate limiting (per-resource?)
	o Defining new hints - guidance is needed on minting new hints.		o Resource Hints
	Possibly a registry.		* indicate a POST to 201 Created pattern
	o Defining new top-level properties - how new ones are minted,		* indicate an "action" POST
	registry, etc.		* outbound links
	o Defining new Resource Object properties - how new ones are minted,		* forms?
	registry, etc.		o Representation Hints
	o Hint to indicate a POST to 201 Created pattern		* format profiles
	o Hint to indicate an "action" POST		* deprecation
	o Describe the extensibility model		o Defining new top-level and resource object properties - how new
	o Allow resources to expose their links		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: http://www.mnot.net/
End of changes. 81 change blocks.
	228 lines changed or deleted		319 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/