diff options
Diffstat (limited to 'doc/rfc/rfc8631.txt')
| -rw-r--r-- | doc/rfc/rfc8631.txt | 563 |
1 files changed, 563 insertions, 0 deletions
diff --git a/doc/rfc/rfc8631.txt b/doc/rfc/rfc8631.txt new file mode 100644 index 0000000..25f1875 --- /dev/null +++ b/doc/rfc/rfc8631.txt @@ -0,0 +1,563 @@ + + + + + + +Internet Engineering Task Force (IETF) E. Wilde +Request for Comments: 8631 July 2019 +Category: Informational +ISSN: 2070-1721 + + + Link Relation Types for Web Services + +Abstract + + 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; see Section 2 of RFC 7841. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + https://www.rfc-editor.org/info/rfc8631. + + + + + + + + + + + + + +Wilde Informational [Page 1] + +RFC 8631 Link Relation Types for Web Services July 2019 + + +Copyright Notice + + Copyright (c) 2019 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 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 Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 + 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 + 3. Web Services . . . . . . . . . . . . . . . . . . . . . . . . 4 + 3.1. Documenting Web Services . . . . . . . . . . . . . . . . 5 + 3.2. Describing Web Services . . . . . . . . . . . . . . . . . 5 + 3.3. Unified Documentation/Description . . . . . . . . . . . . 5 + 4. Link Relations for Web Services . . . . . . . . . . . . . . . 5 + 4.1. The service-doc Link Relation Type . . . . . . . . . . . 6 + 4.2. The service-desc Link Relation Type . . . . . . . . . . . 6 + 4.3. The service-meta Link Relation Type . . . . . . . . . . . 6 + 5. Web Service Status Resources . . . . . . . . . . . . . . . . 7 + 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 + 6.1. Link Relation Type: service-doc . . . . . . . . . . . . . 7 + 6.2. Link Relation Type: service-desc . . . . . . . . . . . . 7 + 6.3. Link Relation Type: service-meta . . . . . . . . . . . . 8 + 6.4. Link Relation Type: status . . . . . . . . . . . . . . . 8 + 7. Security Considerations . . . . . . . . . . . . . . . . . . . 8 + 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 + 8.1. Normative References . . . . . . . . . . . . . . . . . . 9 + 8.2. Informative References . . . . . . . . . . . . . . . . . 9 + Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 9 + Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 + + + + + + + + + + + + +Wilde Informational [Page 2] + +RFC 8631 Link Relation Types for Web Services July 2019 + + +1. 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 in + BCP 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 to RFC 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 2019 + + +3.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 2019 + + +6. IANA Considerations + + The link relation types below have been registered by IANA per + Section 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 8631 + +6.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 8631 + +6.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 8631 + +6.4. Link Relation Type: status + + Relation Name: status + + Description: Identifies a resource that represents the context's + status. + + Reference: RFC 8631 + + + + + + + + + + + +Wilde Informational [Page 8] + +RFC 8631 Link Relation Types for Web Services July 2019 + + +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 (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. References + +8.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 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, + 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 2019 + + +8.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] + |