Expansion

Expansion is a mechanism to embed additional “components”—such as navigation, breadcrumbs, schema, or workflows—within the main content response. This helps the API consumers avoid unnecessary requests.

Say you want to show a document together with the breadcrumbs and a workflow switcher. Instead of doing three individual requests, you can expand the breadcrumbs and the workflow “components” within the document GET request.

The following is a list of components that support expansion.

You can also get the list expandable components by inspecting the @components attribute in the response of any content GET request, as shown in the following example.

GET /en/events HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

Or use the client directly:

import { Client } from '@robgietema/nick';

const cli = Client.initialize({ apiPath: 'http://localhost:8080' });
const login = await cli.login({ username: 'admin', password: 'admin' });

const { data } = await cli.getContent({
  token: login.data.token,
  path: '/en/events',
});

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "title": "Events",
  "@components": {
    "actions": {
      "@id": "http://localhost:8080/en/events/@actions"
    },
    "breadcrumbs": {
      "@id": "http://localhost:8080/en/events/@breadcrumbs"
    },
    "catalog": {
      "@id": "http://localhost:8080/en/events/@catalog"
    },
    "navigation": {
      "@id": "http://localhost:8080/en/events/@navigation"
    },
    "navroot": {
      "@id": "http://localhost:8080/en/events/@navroot"
    },
    "related": {
      "@id": "http://localhost:8080/en/events/@related"
    },
    "translations": {
      "@id": "http://localhost:8080/en/events/@translations"
    },
    "types": {
      "@id": "http://localhost:8080/en/events/@types"
    },
    "workflow": {
      "@id": "http://localhost:8080/en/events/@workflow"
    }
  },
  "@id": "http://localhost:8080/en/events/my-news-item",
  "@type": "Page",
  "id": "events",
  "created": "2022-04-08T16:00:00.000Z",
  "modified": "2022-04-08T16:00:00.000Z",
  "UID": "a95388f2-e4b3-4292-98aa-62656cbd5b9c",
  "is_folderish": true,
  "layout": "view",
  "owner": "admin",
  "review_state": "private",
  "language": {
    "title": "English",
    "token": "en"
  },
  "lock": {
    "locked": false,
    "stealable": true
  }
}

In order to expand and embed the translations component, use the GET parameter expand with the value translations.

GET /en/events/?expand=translations HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

Or use the client directly:

import { Client } from '@robgietema/nick';

const cli = Client.initialize({ apiPath: 'http://localhost:8080' });
const login = await cli.login({ username: 'admin', password: 'admin' });

const { data } = await cli.getContent({
  token: login.data.token,
  path: '/en/events',
  query: {
    expand: 'expanded',
  },
});

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "title": "Events",
  "@components": {
    "actions": {
      "@id": "http://localhost:8080/en/events/@actions"
    },
    "breadcrumbs": {
      "@id": "http://localhost:8080/en/events/@breadcrumbs"
    },
    "catalog": {
      "@id": "http://localhost:8080/en/events/@catalog"
    },
    "navigation": {
      "@id": "http://localhost:8080/en/events/@navigation"
    },
    "navroot": {
      "@id": "http://localhost:8080/en/events/@navroot"
    },
    "related": {
      "@id": "http://localhost:8080/en/events/@related"
    },
    "translations": {
      "@id": "http://localhost:8080/en/events/@translations",
      "items": [
        {
          "@id": "http://localhost:8080/nl/evenementen",
          "language": "nl"
        }
      ],
      "root": {
        "en": "http://localhost:8080/en",
        "nl": "http://localhost:8080/nl"
      }
    },
    "types": {
      "@id": "http://localhost:8080/en/events/@types"
    },
    "workflow": {
      "@id": "http://localhost:8080/en/events/@workflow"
    }
  },
  "@id": "http://localhost:8080/en/events/my-news-item",
  "@type": "Page",
  "id": "events",
  "created": "2022-04-08T16:00:00.000Z",
  "modified": "2022-04-08T16:00:00.000Z",
  "UID": "a95388f2-e4b3-4292-98aa-62656cbd5b9c",
  "is_folderish": true,
  "layout": "view",
  "owner": "admin",
  "review_state": "private",
  "language": {
    "title": "English",
    "token": "en"
  },
  "lock": {
    "locked": false,
    "stealable": true
  }
}