ADP
API Design PrincipleBETA

English

繁體中文

English

繁體中文

Appearance

[ADP-145] Link ​

reviewing phase 1

Add OpenAPI Example and related ADPs

Guidance ​

  • SHOULD include the Link header in responses to provide clients with information about related resources.
  • MUST prioritize existing custom link relation types
  • MUST prioritize IANA-registered link relation types
  • MUST use absolute URIs for custom link relation types
  • MUST use curied link relation types

The Internet Assigned Numbers Authority (IANA) maintains a registry of link relations, which defines common rel values that can be used in the Link header. Some commonly used rel values relevant to API design include:

  • self: Refers to the current resource.
  • next: Refers to the next resource in a sequence.
  • prev: Refers to the previous resource in a sequence.
  • first: Refers to the first resource in a collection.
  • last: Refers to the last resource in a collection.
  • collection: Refers to a collection of resources.
  • item: Refers to an individual item within a collection.
  • profile: Refers to a resource that describes the profile of the current resource.
  • external: Refers to an external resource related to the current resource.
  • curies: Refers to a resource that defines a set of CURIEs (Compact URIs) for use in the document.
  • related: Refers to a related resource that may provide additional context.
  • alternate: Refers to an alternate version of the resource.
  • describedby: Refers to a resource that describes the current resource (e.g., documentation).
  • type: Indicates the media type of the linked resource.
  • canonical: Refers to the preferred version of a resource.

For a complete list of registered link relations, refer to the IANA Link Relation Types.

CURIE Syntax for Custom rel ​

When defining custom rel values, the Common URI Reference Identifier (CURIE) syntax can be used. CURIEs allow for a compact representation of URIs, making it easier to define custom relationships. The syntax is as follows:

http
prefix:local-name

Where prefix is a defined namespace and local-name is the specific relationship. For example:

http
myrel:customRelation

In this case, myrel would be a prefix that maps to a specific namespace, allowing clients to understand the context of the custom relationship.

Syntax ​

The Link header consists of one or more link relations, each defined by a URI and an optional set of attributes. The general syntax is as follows:

http
Link: <URI>; rel="relation"; type="media-type"; title="title"

Attributes ​

  • rel: Indicates the relationship between the current document and the linked resource.

  • type: Specifies the media type of the linked resource (e.g., application/json).

  • title: Provides a human-readable title for the linked resource.

Example ​

Here is an example of a Link header in an HTTP response:

http
Link: <https://api.example.com/users/1>; rel="self", <https://api.example.com/users/2>; rel="next", <https://api.example.com/custom>; rel="myrel:customRelation"

In this example, the response indicates that the current resource can be accessed at https://api.example.com/users/1, the next resource in the sequence is https://api.example.com/users/2, and a custom relationship is defined with myrel:customRelation.

Use Cases ​

  1. Pagination: The Link header is commonly used in APIs to facilitate pagination by providing links to the next and previous pages of results.

  2. Resource Relationships: It can be used to indicate relationships between resources, such as parent-child relationships in hierarchical data.

Design Considerations ​

Hypermedia API (HATEOAS) can replace the role of the Link header, so in some API specifications, if it claims to support HATEOAS, the Link header may be disabled. However, because we do not recommend using HATEOAS, the importance of the Link header is increased.