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.

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.

service-desc Link relation type

One way to point to your OAS document is to use an HTTP Link header with a relation-type (rel value) of service-desc. More information can be found in RFC-8631