doc: Add RFC documents

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]
+