Movatterモバイル変換

Internet Engineering Task Force (IETF)                          E. WildeRequest for Comments: 8631                                     July 2019Category: InformationalISSN: 2070-1721Link Relation Types for Web ServicesAbstract   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   provider.  Often, these sets of resources are referred to as "Web   services" or "Web APIs".  This specification defines link relations   that represent relationships from Web services or APIs to resources   that provide documentation, descriptions, metadata, or status   information for these resources.  Documentation is primarily intended   for human consumers, whereas descriptions are primarily intended for   automated consumers.  Metadata provides information about a service's   context.  This specification also defines a link relation to identify   status resources that are used to represent information about service   status.Status of This Memo   This document is not an Internet Standards Track specification; it is   published for informational purposes.   This document is a product of the Internet Engineering Task Force   (IETF).  It represents the consensus of the IETF community.  It has   received public review and has been approved for publication by the   Internet Engineering Steering Group (IESG).  Not all documents   approved by the IESG are candidates for any level of Internet   Standard; seeSection 2 of RFC 7841.   Information about the current status of this document, any errata,   and how to provide feedback on it may be obtained athttps://www.rfc-editor.org/info/rfc8631.Wilde                         Informational                     [Page 1]

RFC 8631          Link Relation Types for Web Services         July 2019Copyright Notice   Copyright (c) 2019 IETF Trust and the persons identified as the   document authors.  All rights reserved.   This document is subject toBCP 78 and the IETF Trust's Legal   Provisions Relating to IETF Documents   (https://trustee.ietf.org/license-info) in effect on the date of   publication of this document.  Please review these documents   carefully, as they describe your rights and restrictions with respect   to this document.  Code Components extracted from this document must   include Simplified BSD License text as described in Section 4.e of   the Trust Legal Provisions and are provided without warranty as   described in the Simplified BSD License.Table of Contents1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .22.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .43.  Web Services  . . . . . . . . . . . . . . . . . . . . . . . .43.1.  Documenting Web Services  . . . . . . . . . . . . . . . .53.2.  Describing Web Services . . . . . . . . . . . . . . . . .53.3.  Unified Documentation/Description . . . . . . . . . . . .54.  Link Relations for Web Services . . . . . . . . . . . . . . .54.1.  The service-doc Link Relation Type  . . . . . . . . . . .64.2.  The service-desc Link Relation Type . . . . . . . . . . .64.3.  The service-meta Link Relation Type . . . . . . . . . . .65.  Web Service Status Resources  . . . . . . . . . . . . . . . .76.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .76.1.  Link Relation Type: service-doc . . . . . . . . . . . . .76.2.  Link Relation Type: service-desc  . . . . . . . . . . . .76.3.  Link Relation Type: service-meta  . . . . . . . . . . . .86.4.  Link Relation Type: status  . . . . . . . . . . . . . . .87.  Security Considerations . . . . . . . . . . . . . . . . . . .88.  References  . . . . . . . . . . . . . . . . . . . . . . . . .98.1.  Normative References  . . . . . . . . . . . . . . . . . .98.2.  Informative References  . . . . . . . . . . . . . . . . .9   Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . .9   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .9Wilde                         Informational                     [Page 2]

RFC 8631          Link Relation Types for Web Services         July 20191.  Introduction   One of the defining aspects of the Web is that it is possible to   interact with Web resources without any prior knowledge of the   specifics of the resource.  Following the practices described in Web   architecture [W3C.REC-webarch-20041215] by using URIs, HTTP, and   media types, the Web's uniform interface allows interactions with   resources without the more complex binding procedures often necessary   with other approaches.   Many resources on the Web are provided as part of a set of resources   that are referred to as a "Web service" or a "Web API".  In many   cases, these services or APIs are defined and managed as a whole, and   it may be desirable for clients to be able to discover this service   information.   Service information that provides information on how to use service   resources can be broadly separated into two categories: One category   primarily targets human users and often uses generic representations   for human readable documents, such as HTML or PDF.  The other   category is structured information that follows a more formalized   description model and is primarily intended for consumption by   machines -- for example, tools and code libraries.   In the context of this memo, the human-oriented variant is referred   to as "documentation", and the machine-oriented variant is referred   to as "description".   These two categories are not necessarily mutually exclusive, as   representations have been proposed that are intended for both human   consumption and interpretation by machine clients.  In addition, a   typical pattern for service documentation/descriptions is that there   is human-oriented, high-level documentation that is intended to put a   service in context and explain the general model, which is   complemented by machine-level descriptions that are intended as   detailed technical descriptions of the service.  These two resources   could be interlinked, but since they are intended for different   audiences, it can make sense to provide entry points for both of   them.   In addition, while both documentation and descriptions may be   provided as part of a Web service, there may be other information as   well.  Generally speaking, a Web service may have any metadata/   resources associated with it (with documentation and descriptions   being two specific kinds of resources).  If there is a way in which   all of these metadata/resources can be represented, then it should be   possible to find such a resource that provides access to general Web   service metadata.Wilde                         Informational                     [Page 3]

RFC 8631          Link Relation Types for Web Services         July 2019   In addition to these resources about mostly static aspects of a Web   service, this memo also defines a link relation that allows providers   of a Web service to link to a resource that represents status   information about the service.  This information often represents   operational information that allows service consumers to retrieve   information about "service health" and related issues.   This memo places no constraints on the specific representations used   for all of these resources.  It simply allows providers of a Web   service to make the documentation, descriptions, metadata, and status   of their services discoverable and defines link relations that serve   that purpose.2.  Terminology   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and   "OPTIONAL" in this document are to be interpreted as described inBCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all   capitals, as shown here.3.  Web Services   "Web Services" or "Web APIs" (sometimes also referred to as "HTTP   API" or "REST API") expose information and services on the Web.   Following the principles of Web architecture   [W3C.REC-webarch-20041215], they expose URI-identified resources,   which are then accessed and transferred using a specific   representation.  Many services use representations that contain   links, and these links are often typed links.   Using typed links, resources can identify relationship types to other   resources.RFC 8288 [RFC8288] establishes a framework of registered   link relation types, which are identified by simple strings and   registered in an IANA registry.  Any resource that supports typed   links according toRFC 8288 can then use these identifiers to   represent resource relationships on the Web without having to   reinvent registered relation types.   In recent years, Web services, as well as their documentation and   description languages, have gained popularity due to the general   popularity of the Web as a platform for providing information and   services.  However, the design of documentation and description   languages varies according to a number of factors, such as the   general application domain, the preferred application data model, and   the preferred approach for exposing services.Wilde                         Informational                     [Page 4]

RFC 8631          Link Relation Types for Web Services         July 2019   This specification allows service providers to use a unified method   to link to service documentation and/or descriptions.  This link   should not make any assumptions about the provided type of   documentation and/or descriptions, so service providers can choose   those that best fit their services and needs.   This specification also allows service providers to link to general   service metadata.  One part of the metadata may have links to   documentation and/or description as well as other information about a   service, such as deployment or operational information.3.1.  Documenting Web Services   In the context of this specification, "documentation" refers to   information that is primarily intended for human consumption.   Typical representations of this kind of documentation are HTML and   PDF.   Documentation is often structured, but its structure depends on the   structure of the service in question as well as the specific way in   which the authors choose to present it.3.2.  Describing Web Services   In the context of this specification, "description" refers to   information that is primarily intended for machine consumption.   Typical representations are dictated by the technology underlying the   service itself, which means that description formats in today's   technology landscape are based on XML, JSON, Resource Description   Framework (RDF), and a variety of other structured data models.  In   each of those technologies, there may be a variety of languages   defined to serve the same general purpose of describing a Web   service.   Descriptions are always structured, but the structuring principles   depend on the nature of the described service.  For example, one of   the earlier service description approaches, the Web Services   Description Language (WSDL), uses "operations" as its core concept,   which are essentially identical to function calls because the   underlying model is based on the Remote Procedure Call (RPC) model.   Other description languages for non-RPC approaches to services will   use different structuring approaches, such as structuring service   descriptions by URIs and/or URI patterns.Wilde                         Informational                     [Page 5]

RFC 8631          Link Relation Types for Web Services         July 20193.3.  Unified Documentation/Description   If service providers use an approach where there is no distinction   between service documentation (Section 3.1) and service description   (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   previously defined "service" link relation type [RFC5023], which does   not indicate whether it links to documentation or description and   thus may be a better fit if no such differentiation is required.4.  Link Relations for Web Services   In order to allow Web services to represent the relation of   individual resources to service documentation/description and   metadata, this specification introduces and registers three new link   relation types.4.1.  The service-doc Link Relation Type   The "service-doc" link relation type is used to represent the fact   that a resource or a set of resources is documented at a specific   URI.  The target resource is expected to provide documentation that   is primarily intended for human consumption.4.2.  The service-desc Link Relation Type   The "service-desc" link relation type is used to represent the fact   that a resource or a set of resources is described at a specific URI.   The target resource is expected to provide a service description that   is primarily intended for machine consumption.  In many cases, it is   provided in a representation that is consumed by tools, code   libraries, or similar components.4.3.  The service-meta Link Relation Type   The "service-meta" link relation type is used to link to available   metadata for the service context of a resource.  Service metadata is   any kind of data that may be of interest to existing or potential   service users, with documentation/description being only two possible   facets of service metadata.  The target resource is expected to   provide a representation that is primarily intended for machine   consumption.  In many cases, it is provided in a representation that   is consumed by tools, code libraries, or similar components.   Since service metadata can have many different purposes and use many   different representations, it may make sense for representations   using the "service-meta" link relation to offer additional hints   about the specific kind or format of metadata that is being linked.Wilde                         Informational                     [Page 6]

RFC 8631          Link Relation Types for Web Services         July 2019   This definition of the "service-meta" link relation makes no specific   assumptions about how these link hints will be represented, and the   specific mechanism will depend on the context where the "service-   meta" link relation is being used.   One example 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   Web services providing access to one or more resources often are   hosted and operated in an environment for which status information   may be available.  This information may be as simple as confirming   that a service is operational, or it may provide additional   information about different aspects of a service and/or a history of   status information, possibly listing incidents and their resolution.   The "status" link relation type can be used to link to such a status   resource, allowing service consumers to retrieve information about a   Web service's status.  Such a link may not be available for and from   all resources provided by a Web service -- only from key resources   such as a Web service's metadata resource and/or a 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   in any way.  It may be primarily focused on human or machine   consumption or a combination of both.  It may be a simple "traffic   light" indicator for service health or a more sophisticated   representation conveying more detailed information, such as service   subsystems and/or a status history.Wilde                         Informational                     [Page 7]

RFC 8631          Link Relation Types for Web Services         July 20196.  IANA Considerations   The link relation types below have been registered by IANA perSection 4.2 of RFC 8288 [RFC8288].6.1.  Link Relation Type: service-doc   Relation Name:  service-doc   Description:  Identifies service documentation for the context that      is primarily intended for human consumption.   Reference:RFC 86316.2.  Link Relation Type: service-desc   Relation Name:  service-desc   Description:  Identifies service description for the context that is      primarily intended for consumption by machines.   Reference:RFC 86316.3.  Link Relation Type: service-meta   Relation Name:  service-meta   Description:  Identifies general metadata for the context that is      primarily intended for consumption by machines.   Reference:RFC 86316.4.  Link Relation Type: status   Relation Name:  status   Description:  Identifies a resource that represents the context's      status.   Reference:RFC 8631Wilde                         Informational                     [Page 8]

RFC 8631          Link Relation Types for Web Services         July 20197.  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 (particularly its implementation) and to test for   known security issues.  It may thus be advisable to restrict service   descriptions and documentation to aspects of a service that are   necessary 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) 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 (particularly 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.  References8.1.  Normative References   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate              Requirement Levels",BCP 14,RFC 2119,              DOI 10.17487/RFC2119, March 1997,              <https://www.rfc-editor.org/info/rfc2119>.   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase inRFC2119 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,              DOI 10.17487/RFC8288, October 2017,              <https://www.rfc-editor.org/info/rfc8288>.Wilde                         Informational                     [Page 9]

RFC 8631          Link Relation Types for Web Services         July 20198.2.  Informative References   [RFC5023]  Gregorio, J., Ed. and B. de hOra, Ed., "The Atom              Publishing Protocol",RFC 5023, DOI 10.17487/RFC5023,              October 2007, <https://www.rfc-editor.org/info/rfc5023>.   [W3C.REC-webarch-20041215]              Jacobs, I. and N. Walsh, "Architecture of the World Wide              Web, Volume One", World Wide Web Consortium              Recommendation REC-webarch-20041215, December 2004,              <http://www.w3.org/TR/2004/REC-webarch-20041215>.Acknowledgements   Thanks to Mike Amundsen, Ben Campbell, Alissa Cooper, Oliver Gierke,   Benjamin Kaduk, Sebastien Lambla, Darrell Miller, and Adam Roach for   their comments and suggestions.Author's Address   Erik Wilde   Email: erik.wilde@dret.net   URI:http://dret.net/netdret/Wilde                         Informational                    [Page 10]