Links

Thanks to links (hypermedia controls) a client can navigate through the REST API without hardcoding URIs to specific resources. It suffices to know a limited set of entry points and navigate to the desired information. This adds flexibility to the evolution of the API and increases loose coupling between client and server.

When referencing another resource within the same API, a link SHOULD be added using the href attribute.

It is NOT RECOMMENDED to link to resources in other APIs to avoid a tight coupling between the APIs, unless the link target is guaranteed to remain very stable (like the href links to standard problem types [err-problem]).

Entities with a sensitive identifier don’t have their own URI (see [sens-dat]), so they don’t need to be linked.

Each resource MAY also contain its own location in a self attribute at root level of the JSON document.

URIs SHOULD always be absolute.

All href hyperlinks are derived from this minimal link type:

HttpLink JSON schema (from common-v1.yaml)
HttpLink:
  description: A base type of objects representing links to resources.
  type: object
  properties:
    href:
      description: Any absolute URI that is using http or https protocol
      type: string
      format: uri
      readOnly: true

self hyperlinks are derived from the following type:

SelfLink JSON schema (from common-v1.yaml)
SelfLink:
  description: A base type representing a link to the resource's own location within its representation
  type: object
  properties:
    self:
      description: Absolute URI (http or https) to the the resource's own location.
      type: string
      format: uri
      readOnly: true

Links should not be used in request bodies in a PUT, POST or PATCH context, as indicated by the readOnly: true property. In a JSON response, they can be added anywhere.

Example 1. Resource links

GET https://api.example.org/demo/v1/organizations/0202239951

{
  "self": "https://api.example.org/demo/v1/organizations/0202239951"
  "succeededBy": {
    "enterpriseNumber": "0123456789",
    "href": "https://api.example.org/demo/v1/organizations/0123456789"
  },
  "owner": {
    "ssin": "12345678902"
  },
  "website": "https://wwww.myenterprise.com"
}

The href in succeededBy is a link to the corresponding organization’s document resource, while owner is a sensitive identifier and therefore has no link.

PATCH https://api.example.org/demo/v1/organizations/0202239951

{
  "succeededBy": {
    "enterpriseNumber": "0123456789"
  },
  "owner": {
    "ssin": "12345678902"
  },
  "website": "https://wwww.mynewwebsite.com"
}

The corresponding JSON schema includes the link types using allOf. As website isn’t a reference to another API resource, it is not defined using the HttpLink type.

components:
  schemas:
    Organization:
      allOf:
      - "$ref": "./common/v1/common-v1.yaml#/components/schemas/SelfLink"
      - type: object
        properties:
          owner:
            "$ref": "#/components/schemas/PersonReference"
          website:
            type: string
            format: uri
          succeededBy:
            "$ref": "#/components/schemas/OrganizationReference"
    OrganizationReference:
        allOf:
        - type: object
          properties:
            enterpriseNumber:
              "$ref": "./organization-identifier/v1/organization-identifier-v1.yaml#/components/schemas/EnterpriseNumber"
        - "$ref": "./common/v1/common-v1.yaml#/components/schemas/HttpLink"
    PersonReference:
      type: object
      properties:
        ssin:
          "$ref": "./person-identifier/v1/person-identifier-v1.yaml#/components/schemas/Ssin"

Hyperlinks for Pagination inside collections and self-references should use a simple URI value in combination with their corresponding link relations (next, prev, first, last, self) instead of the extensible link type.

The use of Web Linking and Hypertext Application Language (HAL) is not recommended.