< draft-wilde-service-link-rel-06.txt		draft-wilde-service-link-rel-10.txt >
	Network Working Group E. Wilde		Network Working Group E. Wilde
	Internet-Draft CA Technologies		Internet-Draft January 11, 2019
	Intended status: Informational August 1, 2018		Intended status: Informational
	Expires: February 2, 2019		Expires: July 15, 2019
	Link Relation Types for Web Services		Link Relation Types for Web Services
	draft-wilde-service-link-rel-06		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,
	whereas descriptions are primarily intended for automated consumers;		whereas descriptions are primarily intended for automated consumers;
	metadata is supposed to be information about a service's context. It		metadata is supposed to be information about a service's context. It
	also defines a link relation to identify status resources that are		also defines a link relation to identify status resources that are
	used to represent operational information about service status.		used to represent operational information about service status.
	Note to Readers
	Please discuss this draft on the ART mailing list
	(<https://www.ietf.org/mailman/listinfo/art>).
	Online access to all versions and files is available on GitHub
	(<https://github.com/dret/I-D/tree/master/service-link-rel>).
	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 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 February 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 2, line 39 ¶		skipping to change at page 2, line 30 ¶
	4.1. The service-doc Link Relation Type . . . . . . . . . . . 6		4.1. The service-doc Link Relation Type . . . . . . . . . . . 6
	4.2. The service-desc Link Relation Type . . . . . . . . . . . 6		4.2. The service-desc Link Relation Type . . . . . . . . . . . 6
	4.3. The service-meta Link Relation Type . . . . . . . . . . . 6		4.3. The service-meta Link Relation Type . . . . . . . . . . . 6
	5. Web Service Status Resources . . . . . . . . . . . . . . . . 7		5. Web Service Status Resources . . . . . . . . . . . . . . . . 7
	6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7		6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7
	6.1. Link Relation Type: service-doc . . . . . . . . . . . . . 7		6.1. Link Relation Type: service-doc . . . . . . . . . . . . . 7
	6.2. Link Relation Type: service-desc . . . . . . . . . . . . 7		6.2. Link Relation Type: service-desc . . . . . . . . . . . . 7
	6.3. Link Relation Type: service-meta . . . . . . . . . . . . 8		6.3. Link Relation Type: service-meta . . . . . . . . . . . . 8
	6.4. Link Relation Type: status . . . . . . . . . . . . . . . 8		6.4. Link Relation Type: status . . . . . . . . . . . . . . . 8
	7. Security Considerations . . . . . . . . . . . . . . . . . . . 8		7. Security Considerations . . . . . . . . . . . . . . . . . . . 8
	8. References . . . . . . . . . . . . . . . . . . . . . . . . . 8		8. References . . . . . . . . . . . . . . . . . . . . . . . . . 9
	8.1. Normative References . . . . . . . . . . . . . . . . . . 8		8.1. Normative References . . . . . . . . . . . . . . . . . . 9
	8.2. Informative References . . . . . . . . . . . . . . . . . 8		8.2. Informative References . . . . . . . . . . . . . . . . . 9
	Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 9		Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 9
	Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9		Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9
	1. Introduction		1. Introduction
	One of the defining aspects of the Web is that it is possible to		One of the defining aspects of the Web is that it is possible to
	interact with Web resources without any prior knowledge of the		interact with Web resources without any prior knowledge of the
	specifics of the resource. Following Web Architecture		specifics of the resource. Following Web Architecture
	[W3C.REC-webarch-20041215] by using URIs, HTTP, and media types, the		[W3C.REC-webarch-20041215] by using URIs, HTTP, and media types, the
	Web's uniform interface allows interactions with resources without		Web's uniform interface allows interactions with resources without
	skipping to change at page 3, line 27 ¶		skipping to change at page 3, line 19 ¶
	The other category is structured information that follows some more		The other category is structured information that follows some more
	formalized description model, and is primarily intended for		formalized description model, and is primarily intended for
	consumption by machines, for example for tools and code libraries.		consumption by machines, for example for tools and code libraries.
	In the context of this memo, the human-oriented variant is referred		In the context of this memo, the human-oriented variant is referred
	to as "documentation", and the machine-oriented variant is referred		to as "documentation", and the machine-oriented variant is referred
	to as "description".		to as "description".
	These two categories are not necessarily mutually exclusive, as there		These two categories are not necessarily mutually exclusive, as there
	are representations that have been proposed that are intended for		are representations that have been proposed that are intended for
	both human consumption, and for interpretation by machine clients.		both human consumption and interpretation by machine clients. In
	In addition, a typical pattern for service documentation/description		addition, a typical pattern for service documentation/description is
	is that there is human-oriented high-level documentation that is		that there is human-oriented high-level documentation that is
	intended to put a service in context and explain the general model,		intended to put a service in context and explain the general model,
	which is complemented by a machine-level description that is intended		which is complemented by a machine-level description that is intended
	as a detailed technical description of the service. These two		as a detailed technical description of the service. These two
	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 43 ¶		skipping to change at page 5, line 41 ¶
	the earlier service description approaches, the Web Services		the earlier service description approaches, the Web Services
	Description Language (WSDL), uses "operations" as its core concept,		Description Language (WSDL), uses "operations" as its core concept,
	which are essentially identical to function calls, because the		which are essentially identical to function calls, because the
	underlying model is based on that of the Remote Procedure Call (RPC)		underlying model is based on that of the Remote Procedure Call (RPC)
	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 of		If service providers use an approach where there is no distinction
	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 better fit if		no indication of whether it links to documentation or description,
	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
	The link relation types below have been registered by IANA per		The link relation types below have been registered by IANA per
	Section 4.2 of RFC 8288 [RFC8288]:		Section 4.2 of RFC 8288 [RFC8288]:
	6.1. Link Relation Type: service-doc		6.1. Link Relation Type: service-doc
	Relation Name: service-doc		Relation Name: service-doc
	Description: Linking to service documentation that is primarily		Description: Identifies service documentation for the context that
	intended for human consumption.		is primarily intended for human consumption.
	Reference: [[ This document ]]		Reference: [[ This document ]]
	6.2. Link Relation Type: service-desc		6.2. Link Relation Type: service-desc
	Relation Name: service-desc		Relation Name: service-desc
	Description: Linking to service description that is primarily		Description: Identifies service description for the context that
	intended for consumption by machines.		is primarily intended for consumption by machines.
	Reference: [[ This document ]]		Reference: [[ This document ]]
	6.3. Link Relation Type: service-meta		6.3. Link Relation Type: service-meta
	Relation Name: service-meta		Relation Name: service-meta
	Description: Linking to service metadata that is primarily		Description: Identifies general metadata for the context that is
	intended for consumption by machines.		primarily intended for consumption by machines.
	Reference: [[ This document ]]		Reference: [[ This document ]]
	6.4. Link Relation Type: status		6.4. Link Relation Type: status
	Relation Name: status		Relation Name: status
	Description: Linking to a resource that represents the status of a		Description: Identifies a resource that represents the context's
	Web service or API.		status.
	Reference: [[ This document ]]		Reference: [[ This document ]]
	7. Security Considerations		7. Security Considerations
	...		Web service providers should be aware that service descriptions and
			documentation may be used by attackers to gain additional information
			about a service (and in particular its implementation), and to test
			for known security issues. It may thus be advisable to keep service
			descriptions and documentation to those aspects of a service that are
			necessary to use the service, and to exclude any details that are not
			necessary for using the service.
			Another potential security issue for Web service providers is that
			publishing service descriptions and documentation may generally allow
			clients (both malicious and otherwise) a more automated and
			systematic access to a service. It may therefore be possible that
			more of a service's potential vulnerabilities are made easier to find
			and exploit, or simply that a service might receive more load because
			it is accessed by automated clients.
			Web service consumers should be aware that service descriptions and
			documentation can be out of sync or simply incorrect. Blindly
			trusting service descriptions and documentation (in particular when
			descriptions are retrieved and interpreted programmatically) is not a
			safe practice. Web service consumers SHOULD always assume that
			service descriptions and documentation may be incorrect, and SHOULD
			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
	CA Technologies
	Email: erik.wilde@dret.net		Email: erik.wilde@dret.net
	URI: http://dret.net/netdret/		URI: http://dret.net/netdret/
End of changes. 26 change blocks.
	60 lines changed or deleted		89 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/