< draft-nottingham-json-home-01.txt		draft-nottingham-json-home-02.txt >
	Network Working Group M. Nottingham		Network Working Group M. Nottingham
	Internet-Draft Rackspace		Internet-Draft September 13, 2012
	Intended status: Informational July 5, 2012		Intended status: Informational
	Expires: January 6, 2013		Expires: March 17, 2013
	Home Documents for HTTP APIs		Home Documents for HTTP APIs
	draft-nottingham-json-home-01		draft-nottingham-json-home-02
	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
			This draft should be discussed on the apps-discuss mailing list [1].
	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 January 6, 2013.		This Internet-Draft will expire on March 17, 2013.
	Copyright Notice		Copyright Notice
	Copyright (c) 2012 IETF Trust and the persons identified as the		Copyright (c) 2012 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
	skipping to change at page 2, line 22 ¶		skipping to change at page 2, line 23 ¶
	5. Resource Hints . . . . . . . . . . . . . . . . . . . . . . . . 6		5. Resource Hints . . . . . . . . . . . . . . . . . . . . . . . . 6
	5.1. allow . . . . . . . . . . . . . . . . . . . . . . . . . . 7		5.1. allow . . . . . . . . . . . . . . . . . . . . . . . . . . 7
	5.2. representations . . . . . . . . . . . . . . . . . . . . . 7		5.2. representations . . . . . . . . . . . . . . . . . . . . . 7
	5.3. accept-patch . . . . . . . . . . . . . . . . . . . . . . . 7		5.3. accept-patch . . . . . . . . . . . . . . . . . . . . . . . 7
	5.4. accept-post . . . . . . . . . . . . . . . . . . . . . . . 7		5.4. accept-post . . . . . . . . . . . . . . . . . . . . . . . 7
	5.5. accept-put . . . . . . . . . . . . . . . . . . . . . . . . 7		5.5. accept-put . . . . . . . . . . . . . . . . . . . . . . . . 7
	5.6. accept-ranges . . . . . . . . . . . . . . . . . . . . . . 8		5.6. accept-ranges . . . . . . . . . . . . . . . . . . . . . . 8
	5.7. prefer . . . . . . . . . . . . . . . . . . . . . . . . . . 8		5.7. prefer . . . . . . . . . . . . . . . . . . . . . . . . . . 8
	5.8. docs . . . . . . . . . . . . . . . . . . . . . . . . . . . 8		5.8. docs . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
	5.9. precondition-req . . . . . . . . . . . . . . . . . . . . . 8		5.9. precondition-req . . . . . . . . . . . . . . . . . . . . . 8
	5.10. status . . . . . . . . . . . . . . . . . . . . . . . . . . 8		5.10. auth-req . . . . . . . . . . . . . . . . . . . . . . . . . 8
	6. Creating and Serving Home Documents . . . . . . . . . . . . . 8		5.11. status . . . . . . . . . . . . . . . . . . . . . . . . . . 9
			6. Creating and Serving Home Documents . . . . . . . . . . . . . 9
	6.1. Managing Change in Home Documents . . . . . . . . . . . . 9		6.1. Managing Change in Home Documents . . . . . . . . . . . . 9
	6.2. Evolving and Mixing APIs with Home Documents . . . . . . . 9		6.2. Evolving and Mixing APIs with Home Documents . . . . . . . 10
	6.3. Documenting APIs that use Home Documents . . . . . . . . . 10		6.3. Documenting APIs that use Home Documents . . . . . . . . . 10
	7. Consuming Home Documents . . . . . . . . . . . . . . . . . . . 10		7. Consuming Home Documents . . . . . . . . . . . . . . . . . . . 10
	8. Security Considerations . . . . . . . . . . . . . . . . . . . 10		8. Security Considerations . . . . . . . . . . . . . . . . . . . 11
	9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10		9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11
	10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11		10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11
	10.1. Normative References . . . . . . . . . . . . . . . . . . . 11		10.1. Normative References . . . . . . . . . . . . . . . . . . . 11
	10.2. Informative References . . . . . . . . . . . . . . . . . . 11		10.2. Informative References . . . . . . . . . . . . . . . . . . 12
	Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 12		Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 12
	Appendix B. Frequently Asked Questions . . . . . . . . . . . . . 12		Appendix B. Frequently Asked Questions . . . . . . . . . . . . . 13
	B.1. Why not Microformats? . . . . . . . . . . . . . . . . . . 12		B.1. Why not Microformats? . . . . . . . . . . . . . . . . . . 13
	B.2. What about authentication? . . . . . . . . . . . . . . . . 12		B.2. What about authentication? . . . . . . . . . . . . . . . . 13
	B.3. What about 'Faults' (i.e., errors)? . . . . . . . . . . . 12		B.3. What about 'Faults' (i.e., errors)? . . . . . . . . . . . 13
	B.4. How Do I find the XML Schema / JSON Schema / etc. for		B.4. How Do I find the XML Schema / JSON Schema / etc. for
	a particular media type? . . . . . . . . . . . . . . . . . 13		a particular media type? . . . . . . . . . . . . . . . . . 13
	Appendix C. Open Issues . . . . . . . . . . . . . . . . . . . . . 13		B.5. How do I express complex query arguments? . . . . . . . . 14
	Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 13		Appendix C. Open Issues . . . . . . . . . . . . . . . . . . . . . 14
			Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 14
	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") 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 were documented by a document format like
	WADL [1] that is used as a design time description; i.e., the URIs		WADL [2] that is used as a design time description; i.e., the URIs
	and other information they describe are "baked into" client		and other 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 [RFC4288]. 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.
	skipping to change at page 4, line 5 ¶		skipping to change at page 4, line 5 ¶
	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		3. 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,		Its content consists of a root object with a "resources" property, an
	whose names are link relation types (as defined by [RFC5988]), and		object whose names are link relation types (as defined by [RFC5988]),
	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
	skipping to change at page 5, line 11 ¶		skipping to change at page 5, line 11 ¶
	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;
			i.e., one Resource Object per relation type.
	4. Resource Objects		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.
	Resource Objects MUST have only and exactly one of the "href" and		Resource Objects MUST have only and exactly one of the "href" and
	"href-template" properties.		"href-template" properties.
	skipping to change at page 8, line 38 ¶		skipping to change at page 8, line 38 ¶
	referring to documentation that SHOULD be in HTML format.		referring to documentation that SHOULD be in HTML format.
	5.9. precondition-req		5.9. precondition-req
	Hints that the resource requires state-changing requests (e.g., PUT,		Hints that the resource requires state-changing requests (e.g., PUT,
	PATCH) to include a precondition, as per		PATCH) to include a precondition, as per
	[I-D.ietf-httpbis-p4-conditional], to avoid conflicts due to		[I-D.ietf-httpbis-p4-conditional], to avoid conflicts due to
	concurrent updates.		concurrent updates.
	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 type of precondition expected.		"last-modified" indicating type of precondition expected.
	5.10. status		5.10. auth-req
			Hints that the resource requires authentication using the HTTP
			Authentication Framework [I-D.ietf-httpbis-p7-auth].
			Content MUST be an array of objects, each with a "scheme" property
			containing a string that corresponds to a HTTP authentication scheme,
			and optionally a "realms" property containing an array of zero to
			many strings that identify protection spaces that the resource is a
			member of.
			For example, a Resource Object might contain the following hint:
			{
			"auth-req": [
			{
			"scheme": "Basic",
			"realms": ["private"]
			}
			]
			}
			5.11. status
	Hints the status of the resource.		Hints the status of the resource.
	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 can still be used.		recommended, but it is still available.
			o "gone" - indicates that the resource is no longer available; i.e.,
			it will return a 410 Gone HTTP status code if accessed.
	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
	skipping to change at page 10, line 43 ¶		skipping to change at page 11, line 20 ¶
	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		TBD
			Clients need to exercise care when using hints. For example, a naive
			client might send credentials to a server that uses the auth-req
			hint, without checking to see if those credentials are appropriate
			for that server.
	9. IANA Considerations		9. IANA Considerations
	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., Lafon, Y., Nottingham, M., and J. Reschke,
	"HTTP/1.1, part 6: Caching",		"HTTP/1.1, part 6: Caching",
	draft-ietf-httpbis-p6-cache-19 (work in progress),		draft-ietf-httpbis-p6-cache-19 (work in progress),
	March 2012.		March 2012.
	[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.
	skipping to change at page 11, line 41 ¶		skipping to change at page 12, line 24 ¶
	4: Conditional Requests",		4: Conditional Requests",
	draft-ietf-httpbis-p4-conditional-19 (work in progress),		draft-ietf-httpbis-p4-conditional-19 (work in progress),
	March 2012.		March 2012.
	[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, "HTTP/1.1, part
	5: Range Requests and Partial Responses",		5: Range Requests and Partial Responses",
	draft-ietf-httpbis-p5-range-19 (work in progress),		draft-ietf-httpbis-p5-range-19 (work in progress),
	March 2012.		March 2012.
			[I-D.ietf-httpbis-p7-auth]
			Fielding, R., Lafon, Y., and J. Reschke, "HTTP/1.1, part
			7: Authentication", draft-ietf-httpbis-p7-auth-19 (work in
			progress), March 2012.
	[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-12 (work in progress),
	February 2012.		February 2012.
	[RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and		[RFC4288] Freed, N. and J. Klensin, "Media Type Specifications and
	Registration Procedures", BCP 13, RFC 4288, December 2005.		Registration Procedures", BCP 13, RFC 4288, December 2005.
	[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		URIs
	[1] <http://www.w3.org/Submission/wadl/>		[1] <https://www.ietf.org/mailman/listinfo/apps-discuss>
	[2] <http://microformats.org/>		[2] <http://www.w3.org/Submission/wadl/>
			[3] <http://microformats.org/>
	Appendix A. Acknowledgements		Appendix A. Acknowledgements
	Thanks to Mike Amundsen, Bill Burke, Graham Klyne, Leif Hedstrom, and		Thanks to Jan Algermissen, Mike Amundsen, Bill Burke, Graham Klyne,
	Jeni Tennison for their suggestions and feedback.		Leif Hedstrom, Jeni Tennison and Jorge Williams for their suggestions
			and feedback.
	Appendix B. Frequently Asked Questions		Appendix B. Frequently Asked Questions
	B.1. Why not Microformats?		B.1. Why not Microformats?
	Browser-centric Web applications use HTML as their representation		Browser-centric Web applications use HTML as their representation
	format of choice. While it is possible to augment HTML for non-		format of choice. While it is possible to augment HTML for non-
	browser clients (using techniques like Microformats [2] ), a few		browser clients (using techniques like Microformats [3] ), a few
	issues become evident when doing so:		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
	skipping to change at page 13, line 23 ¶		skipping to change at page 14, line 12 ¶
	So, this is an area of possible future development; if any such		So, this is an area of possible future development; if any such
	mechanism appears here, it's likely to be quite restricted.		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		B.4. How Do I find the XML Schema / JSON Schema / etc. for a particular
	media type?		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?
			Complex queries -- i.e., those that exceed the expressive power of
			Link Templates or would require ambiguous properties of a "resources"
			object -- aren't intended to be defined by a home document. The
			appropriate way to do this is with a "form" language, much as HTML
			defines.
			Future revisions of this specification may define or accommodate the
			use of such a form in the home 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 Refining and extending representation formats - "application/xml",
	for example, isn't enough. While a media type for every		for example, isn't enough. While a media type for every
	representation is one answer, something like 'profile' might be		representation is one answer, something like 'profile' might be
	good too.		good too.
	o Object for contact details - do we need an object that describes		o Object for contact details - do we need an object that describes
	who's running the API, etc?		who's running the API, etc?
	o Defining new hints - guidance is needed on minting new hints.		o Defining new hints - guidance is needed on minting new hints.
	Possibly a registry.		Possibly a registry.
	o Defining new top-level properties - how new ones are minted,		o Defining new top-level properties - how new ones are minted,
	registry, etc.		registry, etc.
	o Defining new Resource Object properties - how new ones are minted,		o Defining new Resource Object properties - how new ones are minted,
	registry, etc.		registry, etc.
			o Hint to indicate a POST to 201 Created pattern
			o Hint to indicate an "action" POST
			o Describe the extensibility model
			o Allow resources to expose their links
	Author's Address		Author's Address
	Mark Nottingham		Mark Nottingham
	Rackspace
	Email: mnot@mnot.net		Email: mnot@mnot.net
	URI: http://www.mnot.net/		URI: http://www.mnot.net/
End of changes. 26 change blocks.
	30 lines changed or deleted		91 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/