MUST include links to other resources [52]

What is hypermedia in REST API?

The term “hypermedia” refers to any content that contains links to other forms of media such as images, movies, and text. REST architectural style lets us use the hypermedia links in the API response contents. It allows the client to dynamically navigate to the appropriate resources by traversing the hypermedia links.

Always refer to other resources via a sub-object. The name of the field (“payer” in the example below) describes the role/function. You must include a links section with a related attribute that specifies a relative path to the related resource. Do not put the entire URL (incl. hostname) in the link. With a relative path there is no need to rewrite URLs on different environments. Do not wrap the referenced resource attributes in a data object, because that would prevent you to move an object to a separate API without breaking changes: a link to an separate API would in that case require a data wrapper while the object as part of its parent would not.

{
  "payer": {
    "links": {
      "related": "/debtors/v1/599000"
    }, 
    "id": "599000"
  }
}

The corresponding schema should be like:

payer:
  type: object
  properties:
    links:
      type: object
      properties:
        related:
          type: string
          description: Link to other resource
    id:
      $ref: ../some-business-object.yml/properties/id

MAY include additional attributes [53]

The additional attributes should only be used as convenience for the consumer when retrieving these attributes via the related API is very cumbersome. The additional fields can also be used in case the system is consciously replicating data with read-only characteristics to allow filtering and/or searching.

The sub-object provides the ability to add additional attributes, like i.e. firstName, as optimization:

{
  "payer": {
    "links": {
      "related": "/debtors/v1/599000"
    }, 
    "id": "599000",
    "firstName": "Jan"
  }
}

SHOULD follow original linked API structure [54]

The additional attributes (here above firstName) should follow the original linked API structure on best effort. This means, that if there are sub-levels in the linked API like address and then street inside that, you should follow that structure on best effort. The most important attribute of the linked API stays the id attribute.

SHOULD ignore other fields than the id on update or create in the links [55]

On update or create (POST/PUT/PATCH) all fields other than the id should be ignored by the implementation. In the openAPI specification the links may be documented in the update and create operations

POST operation example which is equal to the GET operation:

{
  "payer": {
    "links": {
      "related": "/debtors/v1/599000"
    }, 
    "id": "599000",
    "firstName": "Jan"
  }
}

SHOULD be placed in an array when there are multiple references possible [56]

When there are multiple references possible, the references should be placed in an array. In example, a picture can be taken with multiple meters or connections on it. Multiple eancodes than can be added to the metadata of the picture. The reference in the picture API could then look like this:

{
  "pictureFileName": "meterkast1.jpg",
  "connections": [
      {
          "links": {
              "related": "/connections/v1/12345"
          },
          "id": "12345",
          "eanCode": "12345"
      },
      {
          "links": {
              "related": "/connections/v1/6789"
          },
          "id": "6789",
          "eanCode": "6789"
      }
  ]
}