Hypermedia Controls

Hypermedia control is a strategy to encode resource navigation and manipulation within the messages exchanged through an API.

The AlpineBits® standard adopts the hypermedia strategy defined in JSON:API v1.0, which is briefly described in the following paragraphs.

To provide hypermedia controls for CLIENTS to navigate the API, a SERVER MUST include a links object according to what is defined in this standard.

A SERVER MUST include a links object with self link to the root of every message representing the link used by CLIENT in the request that generates that response.

{
  "links": {
    "self": "www.example.com/2022-04/events?fields[events]=name,publisher",
    ...
  },
  "data": [ ... ]
  ...
}

A SERVER MUST include a links object with self link to the root of every resource representing its individual resource route (see ???).

{
  "links": { ... },
  "data": [
    {
      "id": "123",
      "type": "events",
      "meta": { ... },
      "links": {
        "self": "www.example.com/2022-04/events/123",
        ...
      },
      "attributes": { ... },
      "relationships": { ... }
    },
    ...
  ]
  ...
}

A SERVER MUST include a links object with related link to every non-null relationship object (alongside the data field) representing the resource relationship route where the related resource(s) are available at (see ???).

{
  "links": { ... },
  "data": [
    {
      "id": "123",
      "type": "events",
      "meta": { ... },
      "links": { ... },
      "attributes": { ... },
      "relationships": {
        "publisher": {
          "data": {
            "id": "456",
            "type": "agents"
          },
          "links": {
            "related": "www.example.com/2022-04/events/123/publisher"
          }
        },
        ...
      }
    },
    ...
  ]
  ...
}

A CLIENT SHOULD NOT include any links objects to its messages. A SERVER MUST ignore any links objects in messages from CLIENTS.

Action Discovery

SERVERS that support additional HTTP methods SHOULD support link:https://jsonapi.org/faq/#how-to-discover-resource-possible-actionsaction discovery.

To do so, a SERVER needs to:

• Support HEAD requests on all of its endpoints

• Answer HEAD requests with messages containing an Allow header listing the HTTP methods it supports on the requested endpoint.

The following two snippets exemplify a HEAD request made by a CLIENT and its response sent by a SERVER.

HEAD /2022-04/events HTTP/1.1
Host: \https://example.com/
Authorization: Basic Y2hyaXM6c2VjcmV0

HTTP/1.1 200 OK
Allow: GET,POST,PATCH,DELETE

A response message to a HEAD request message does not contain a body.