    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]