< draft-wilde-service-link-rel-08.txt		draft-wilde-service-link-rel-10.txt >
	Network Working Group E. Wilde		Network Working Group E. Wilde
	Internet-Draft November 29, 2018		Internet-Draft January 11, 2019
	Intended status: Informational		Intended status: Informational
	Expires: June 2, 2019		Expires: July 15, 2019
	Link Relation Types for Web Services		Link Relation Types for Web Services
	draft-wilde-service-link-rel-08		draft-wilde-service-link-rel-10
	Abstract		Abstract
	Many resources provided on the Web are part of sets of resources that		Many resources provided on the Web are part of sets of resources that
	are provided in a context that is managed by one particular service		are provided in a context that is managed by one particular service
	provider. Often, these sets of resources are referred to as "Web		provider. Often, these sets of resources are referred to as "Web
	Services" or "Web APIs". This specification defines link relations		Services" or "Web APIs". This specification defines link relations
	for representing relationships from those resources to ones that		for representing relationships from those resources to ones that
	provide documentation, descriptions, or metadata for these Web		provide documentation, descriptions, or metadata for these Web
	services. Documentation is primarily intended for human consumers,		services. Documentation is primarily intended for human consumers,
	skipping to change at page 1, line 40 ¶		skipping to change at page 1, line 40 ¶
	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 https://datatracker.ietf.org/drafts/current/.		Drafts is at https://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 June 2, 2019.		This Internet-Draft will expire on July 15, 2019.
	Copyright Notice		Copyright Notice
	Copyright (c) 2018 IETF Trust and the persons identified as the		Copyright (c) 2019 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
	(https://trustee.ietf.org/license-info) in effect on the date of		(https://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
	skipping to change at page 3, line 35 ¶		skipping to change at page 3, line 35 ¶
	resources could be interlinked, but since they are intended for		resources could be interlinked, but since they are intended for
	different audiences, it can make sense to provide entry points for		different audiences, it can make sense to provide entry points for
	both of them.		both of them.
	In addition, while both documentation and descriptions may be		In addition, while both documentation and descriptions may be
	provided as part of a Web service, there may be other information as		provided as part of a Web service, there may be other information as
	well. Generally speaking, a Web service may have any metadata/		well. Generally speaking, a Web service may have any metadata/
	resources associated with it (with documentation/description just		resources associated with it (with documentation/description just
	being two specific kinds of resource). If there is a way how all of		being two specific kinds of resource). If there is a way how all of
	these metadata/resources are represented, then it should be possible		these metadata/resources are represented, then it should be possible
	to discover such a resource of general Web service metadata.		to discover such a resource providing access to general Web service
			metadata.
	In addition to these resources about mostly static aspects of a Web		In addition to these resources about mostly static aspects of a Web
	service, this memo also defines a link relation that allows providers		service, this memo also defines a link relation that allows providers
	of a Web service to link to a resource that represents status		of a Web service to link to a resource that represents status
	information about the service. This information often represents		information about the service. This information often represents
	operational information that allows service consumers to retrieve		operational information that allows service consumers to retrieve
	information about "service health" and related issues.		information about "service health" and related issues.
	This memo places no constraints on the specific representations used		This memo places no constraints on the specific representations used
	for all of these resources. It simply allows providers of a Web		for all of these resources. It simply allows providers of a Web
	service to make the documentation, description, metadata, and status		service to make the documentation, description, metadata, and status
	of their services discoverable, and defines link relations that serve		of their services discoverable, and defines link relations that serve
	that purpose.		that purpose.
	2. Terminology		2. Terminology
	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", "NOT RECOMMENDED", "MAY", and
	document are to be interpreted as described in RFC 2119 [RFC2119].		"OPTIONAL" in this document are to be interpreted as described in BCP
			14 [RFC2119] [RFC8174] when, and only when, they appear in all
			capitals, as shown here.
	3. Web Services		3. Web Services
	"Web Services" or "Web APIs" (sometimes also referred to as "HTTP		"Web Services" or "Web APIs" (sometimes also referred to as "HTTP
	API" or "REST API") are a way to expose information and services on		API" or "REST API") are a way to expose information and services on
	the Web. Following the principles of Web architecture		the Web. Following the principles of Web architecture
	[W3C.REC-webarch-20041215], they expose URI-identified resources,		[W3C.REC-webarch-20041215], they expose URI-identified resources,
	which are then accessed and transferred using a specific		which are then accessed and transferred using a specific
	representation. Many services use representations that contain		representation. Many services use representations that contain
	links, and often these links are typed links.		links, and often these links are typed links.
	skipping to change at page 5, line 45 ¶		skipping to change at page 5, line 45 ¶
	model. Other description languages for non-RPC approaches to		model. Other description languages for non-RPC approaches to
	services will use different structuring approaches, such as		services will use different structuring approaches, such as
	structuring service descriptions by URIs and/or URI patterns.		structuring service descriptions by URIs and/or URI patterns.
	3.3. Unified Documentation/Description		3.3. Unified Documentation/Description
	If service providers use an approach where there is no distinction		If service providers use an approach where there is no distinction
	between service documentation (Section 3.1) and service description		between service documentation (Section 3.1) and service description
	(Section 3.2), then they may not feel the need to use two separate		(Section 3.2), then they may not feel the need to use two separate
	links. In such a case, an alternative approach is to use the		links. In such a case, an alternative approach is to use the
	"service" link relation type, which has no indication of whether it		previously defined "service" link relation type [RFC5023], which has
	links to documentation or description, and thus may be a better fit		no indication of whether it links to documentation or description,
	if no such differentiation is required.		and thus may be a better fit if no such differentiation is required.
	4. Link Relations for Web Services		4. Link Relations for Web Services
	In order to allow Web services to represent the relation of		In order to allow Web services to represent the relation of
	individual resources to service documentation/description and		individual resources to service documentation/description and
	metadata, this specification introduces and registers three new link		metadata, this specification introduces and registers three new link
	relation types.		relation types.
	4.1. The service-doc Link Relation Type		4.1. The service-doc Link Relation Type
	The "service-doc" link relation type is used to represent the fact		The "service-doc" link relation type is used to represent the fact
	that a resource is part of a bigger set of resources that are		that a resource or a set of resources are documented at a specific
	documented at a specific URI. The target resource is expected to		URI. The target resource is expected to provide documentation that
	provide documentation that is primarily intended for human		is primarily intended for human consumption.
	consumption.
	4.2. The service-desc Link Relation Type		4.2. The service-desc Link Relation Type
	The "service-desc" link relation type is used to represent the fact		The "service-desc" link relation type is used to represent the fact
	that a resource is part of a bigger set of resources that are		that a resource or a set of resources are described at a specific
	described at a specific URI. The target resource is expected to		URI. The target resource is expected to provide a service
	provide a service description that is primarily intended for machine		description that is primarily intended for machine consumption. In
	consumption. In many cases, it is provided in a representation that		many cases, it is provided in a representation that is consumed by
	is consumed by tools, code libraries, or similar components.		tools, code libraries, or similar components.
	4.3. The service-meta Link Relation Type		4.3. The service-meta Link Relation Type
	The "service-meta" link relation type is used to link to available		The "service-meta" link relation type is used to link to available
	metadata for the service context of a resource. Service metadata is		metadata for the service context of a resource. Service metadata is
	any kind of data that may be of interest to existing or potential		any kind of data that may be of interest to existing or potential
	service users, with documentation/description only being two possible		service users, with documentation/description only being two possible
	facets of service metadata. The target resource is expected to		facets of service metadata. The target resource is expected to
	provide a service description that is primarily intended for machine		provide a representation that is primarily intended for machine
	consumption. In many cases, it is provided in a representation that		consumption. In many cases, it is provided in a representation that
	is consumed by tools, code libraries, or similar components.		is consumed by tools, code libraries, or similar components.
	Since service metadata can be for many different purposes, and use		Since service metadata can be for many different purposes, and use
	many different representations, it may make sense for representations		many different representations, it may make sense for representations
	using the "service-meta" link relation to add additional hints about		using the "service-meta" link relation to add additional hints about
	the specific kind or format of metadata that is being linked. This		the specific kind or format of metadata that is being linked. This
	definition of the "service-meta" link relation makes no specific		definition of the "service-meta" link relation makes no specific
	assumptions about how these link hints will be represented, and the		assumptions about how these link hints will be represented, and the
	specific mechanism will depend on the context where the "service-		specific mechanism will depend on the context where the "service-
	meta" link relation is being used.		meta" link relation is being used.
			One example for this is that a "service-desc" link may identify an
			OpenAPI description, which is supposed to be the machine-readable
			description of a Web API. A "service-meta" link may identify a
			resource that contains additional metadata about the Web API, such as
			labels that classify the API according to a labeling scheme, and a
			privacy policy that makes statements about how the Web API manages
			personally identifiable information.
	5. Web Service Status Resources		5. Web Service Status Resources
	Web services providing access to a set of resources often are hosted		Web services providing access to one or more resources often are
	and operated in an environment for which status information may be		hosted and operated in an environment for which status information
	available. This information may be as simple as confirming that a		may be available. This information may be as simple as confirming
	service is operational, or may provide additional information about		that a service is operational, or may provide additional information
	different aspects of a service, and/or a history of status		about different aspects of a service, and/or a history of status
	information, possibly listing incidents and their resolution.		information, possibly listing incidents and their resolution.
	The "status" link relation type can be used to link to such a status		The "status" link relation type can be used to link to such a status
	resource, allowing service consumers to retrieve status information		resource, allowing service consumers to retrieve status information
	about a Web service's status. Such a link may not be available for		about a Web service's status. Such a link may not be available for
	and from all resources provided by a Web service, but from key		and from all resources provided by a Web service, but from key
	resources such as a Web service's metadata resource and/or a		resources such as a Web service's metadata resource and/or a
	service's home resource [I-D.nottingham-json-home].		service's home resource (i.e., a resource analogous to the home page
			of a Web site).
	This memo does not restrict the representation of a status resource		This memo does not restrict the representation of a status resource
	in any way. It may be primarily focused on human or machine		in any way. It may be primarily focused on human or machine
	consumption, or a combination of both. It may be a simple "traffic		consumption, or a combination of both. It may be a simple "traffic
	light" indicator for service health, or a more sophisticated		light" indicator for service health, or a more sophisticated
	representation conveying more detailed information such as service		representation conveying more detailed information such as service
	subsystems and/or a status history.		subsystems and/or a status history.
	6. IANA Considerations		6. IANA Considerations
	skipping to change at page 8, line 27 ¶		skipping to change at page 8, line 29 ¶
	Description: Identifies a resource that represents the context's		Description: Identifies a resource that represents the context's
	status.		status.
	Reference: [[ This document ]]		Reference: [[ This document ]]
	7. Security Considerations		7. Security Considerations
	Web service providers should be aware that service descriptions and		Web service providers should be aware that service descriptions and
	documentation may be used by attackers to gain additional information		documentation may be used by attackers to gain additional information
	about a service, and to test for known security issues. It may thus		about a service (and in particular its implementation), and to test
	be advisable to keep service descriptions and documentation to those		for known security issues. It may thus be advisable to keep service
	aspects of a service that are necessary to use the service, and to		descriptions and documentation to those aspects of a service that are
	exclude any implementation details that are not necessary for using		necessary to use the service, and to exclude any details that are not
	the service.		necessary for using the service.
	Another potential security issue for Web service providers is that		Another potential security issue for Web service providers is that
	publishing service descriptions and documentation may generally allow		publishing service descriptions and documentation may generally allow
	clients (both malicious and otherwise) a more automated and		clients (both malicious and otherwise) a more automated and
	systematic access to a service. It may therefore be possible that		systematic access to a service. It may therefore be possible that
	more of a service's potential vulnerabilities are made easier to find		more of a service's potential vulnerabilities are made easier to find
	and exploit, or simply that a service might receive more load because		and exploit, or simply that a service might receive more load because
	it is accessed by automated clients.		it is accessed by automated clients.
	Web service consumers should be aware that service descriptions and		Web service consumers should be aware that service descriptions and
	documentation can be out of sync or simply incorrect. Blindly		documentation can be out of sync or simply incorrect. Blindly
	trusting service descriptions and documentation (in particular when		trusting service descriptions and documentation (in particular when
	descriptions are retrieved and interpreted programmatically) is not a		descriptions are retrieved and interpreted programmatically) is not a
	safe practice. Web service consumers should always assume that		safe practice. Web service consumers SHOULD always assume that
	service descriptions and documentation may be incorrect, and should		service descriptions and documentation may be incorrect, and SHOULD
	behave accordingly.		therefore be prepared to handle errors at runtime.
	8. References		8. References
	8.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", RFC 2119, March 1997.		Requirement Levels", RFC 2119, March 1997.
			[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
			2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
			May 2017, <https://www.rfc-editor.org/info/rfc8174>.
	[RFC8288] Nottingham, M., "Web Linking", RFC 8288,		[RFC8288] Nottingham, M., "Web Linking", RFC 8288,
	DOI 10.17487/RFC8288, October 2017,		DOI 10.17487/RFC8288, October 2017,
	<https://www.rfc-editor.org/info/rfc8288>.		<https://www.rfc-editor.org/info/rfc8288>.
	8.2. Informative References		8.2. Informative References
	[I-D.nottingham-json-home]		[RFC5023] Gregorio, J., Ed. and B. de hOra, Ed., "The Atom
	Nottingham, M., "Home Documents for HTTP APIs", draft-		Publishing Protocol", RFC 5023, DOI 10.17487/RFC5023,
	nottingham-json-home-04 (work in progress), May 2016.		October 2007, <https://www.rfc-editor.org/info/rfc5023>.
	[W3C.REC-webarch-20041215]		[W3C.REC-webarch-20041215]
	Jacobs, I. and N. Walsh, "Architecture of the World Wide		Jacobs, I. and N. Walsh, "Architecture of the World Wide
	Web, Volume One", World Wide Web Consortium		Web, Volume One", World Wide Web Consortium
	Recommendation REC-webarch-20041215, December 2004,		Recommendation REC-webarch-20041215, December 2004,
	<http://www.w3.org/TR/2004/REC-webarch-20041215>.		<http://www.w3.org/TR/2004/REC-webarch-20041215>.
	Appendix A. Acknowledgements		Appendix A. Acknowledgements
	Thanks for comments and suggestions provided by Mike Amundsen, Oliver		Thanks for comments and suggestions provided by Mike Amundsen, Ben
	Gierke, Sebastien Lambla, and Darrell Miller.		Campbell, Alissa Cooper, Oliver Gierke, Benjamin Kaduk, Sebastien
			Lambla, Darrell Miller, and Adam Roach.
	Author's Address		Author's Address
	Erik Wilde		Erik Wilde
	Email: erik.wilde@dret.net		Email: erik.wilde@dret.net
	URI: http://dret.net/netdret/		URI: http://dret.net/netdret/
End of changes. 19 change blocks.
	40 lines changed or deleted		56 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/