erik.wilde@dret.net http://dret.net/netdret/

Many resources provided on the Web are part of a sets of resources that are provided in a context that is defined and managed by one particular service provider. Often, these sets of resources are referred to as "Web Services" or "Web APIs". This specification defines two link relations that allow to represent relationships from those resources to ones that provide documentation or descriptions of the Web services. The difference between these concepts is that documentation is primarily intended for human consumers, whereas descriptions are primarily intended for automated consumers. Please discuss this draft on the apps-discuss mailing list. Online access to all versions and files is available on GitHub.

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 , by using URIs, HTTP, and media types, the Web's uniform interface allows interactions with resources without the more complex binding procedures of other approaches. However, 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 definition information. Service definition can be broadly separated into two categories: One category is primarily targeted for human users and often uses generic formats for human readable documents, such as HTML or PDF. The other category is structured information that followed some more formalized description model, and is primarily intended for consumption by machines, for example for tools and code libraries. In the context of this specification, 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 there are formats that have been proposed that are intended for both human consumption, and for interpretation by machine clients. This specification places no constraints on the specific formats used for either of those two categories. It simply allows publishers of a Web service to make the documentation and/or the description of their services discoverable, and defines two link relations that serve that purpose.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 .

"Web Services" or "Web APIs" (sometimes also referred to as "HTTP API" or "REST API") are a way to expose information and services on the Web. Following the principles of Web architecture , they expose URI-identified resources, which are then accessed and transferred using a specific representation. Many services use representations that contain links, and often these links are typed links. Using typed links, resources can identify relationship types to other resources. RFC 5988 establishes a framework of well-known 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 5988 can then use these identifiers to represent resource relationships on the Web without having to re-invent 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 with a number of factors, such as the general application domain, the preferred application data model, and the preferred approach for exposing services. This specification allows service providers to use a unified way to link to service documentation and/or description. This link should not make any assumptions about the provided type of documentation and/or description, so that service providers can choose the ones that best fit their services and needs.

In the context of this specification, "documentation" refers to information that is primarily intended for human consumption. Typical formats for this kind of documentation are HTML and PDF. Documentation is often structured, but the exact kind of structure depends on the structure of the service that is documented, as well as on the specific way in which the documentation authors choose to document it.

In the context of this specification, "description" refers to information that is primarily intended for machine consumption. Typical formats for this are dictated by the technology underlying the service itself, which means that in today's technology landscape, description formats exist that are based on XML, JSON, RDF, and a variety of other structured data models. Also, in each of those technologies, there may be a variety of languages that are defined to achieve 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 that of the Remote Procedure Call (RPC) model. Other description languages for non-RPC approaches to services will use different structuring approaches.

In order to allow Web services to represent the relation of individual resources to service documentation or description, this specification introduces and registers two new link relation types.

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 documented at a specific URI. The target resource is expected to provide documentation that is primarily intended for human consumption.

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 described at a specific URI. The target resource is expected to provide a service description that is primarily intended for machine consumption. Very often, it is provided in a format that is consumed by tools, code libraries, or similar components.

The link relation types below have been registered by IANA per Section 6.2.1 of RFC 5988 :

Relation Name: service-doc Description: Linking to service documentation that is primarily intended for human consumption. Reference: [[ This document ]]

Relation Name: service-desc Description: Linking to service description that is primarily intended for consumption by machines. Reference: [[ This document ]]

...

Note to RFC Editor: Please remove this section before publication.

Variety of minor text edits. See GitHub repository for details.

Thanks for comments and suggestions provided by Mike Amundsen and Darrell Miller.