References

Authentication

To get the content (live or preview), a client needs to have a OAuth2 Bearer Token.

The oauth flow has not been publicly exposed so you’ll have to created one manually if you own the Authentication Server or ask NHS.UK for one if you want to set up a client.

A default OAuth client and access token for the NHS.UK frontend app is created automatically during the db migration process. This can be obtained via the django admin area or by quering the db.

When requesting some content, you need to supply the access token as a Authorization request header e.g.:

curl -v https://<url>/ -H 'Authorization: Bearer <access-token>'

Content API

Endpoints

Get all live pages

/api/pages/

Returns the list of all live pages in basic format which does not include all the fields.

Example of response:

{
    "meta": {
        "totalCount": 2
    },
    "items": [
        {
            "id": 1,
            "meta": {
                ...
            },
            "title": "..."
        },
        ...
    ]
}

Get a live page by id

/api/pages/<id>/

e.g. /api/pages/1/

Returns the details of the page with given id split into meta fields and page fields.

Example of response:

{
    "id": 5,
    "meta": {
        ...
    },

    "title": "...",
    ...
}

Get a live page by path

/api/pages/with-path/<path>/

e.g. /api/pages/with-path/conditions/hernia/

Returns the details of the page with given path split into meta fields and page fields.

The response is exactly the same as the one returned by Get a live page by id.

Example of response:

{
    "id": 5,
    "meta": {
        ...
    },

    "title": "...",
    ...
}

Meta fields

The meta field defines the following metadata:

  1. type: the page type. E.g. pages.EditorialPage
  2. slug: the relative slug value of the page. Note that this does not include the parent path
  3. parent: details of the parent page in basic mode
  4. children: ordered list of live child pages in basic mode
  5. siblings: ordered list of live siblings, including the current page, in basic mode

Content Preview API

Endpoints

Get a version of the page

/api/preview-pages/<page-id>/?revision-id=<revision-id>

e.g. /api/preview-pages/5/?revision-id=8

Returns the content of the page with id == page-id for the revision with id == revision-id if specified, or the latest revision otherwise.

The response is exactly the same as the one returned by Get a live page by id.

Images

Data

Information about images is returned as part of the Content API.

Format:

{
  "id": 1,
  "meta": {
      "type": "images.Image",
      "detailUrl": "<backend-url>/api/images/1/",
      "tags": []
  },
  "title": "...",
  "width": 1000,
  "height": 500,
  "caption": "",
  "slug": "<slug>.jpeg",
  "version": 1

}

Where:

  1. title: used for alt text
  2. width and height: size of the original image
  3. caption: caption
  4. slug: slug of the image. Can be used to compose the image path in a user-friendly way
  5. version: integer incremented every time the image is saved. Can be used to invalidate the cache when composing the image path

Serving

The endpoint for serving images is:

/images/<signature>/<id>/<filter-spec>/<version>/<slug>

Where:

  1. signature: is the HMAC of some data using a private key (see below)
  2. id: id of the image
  3. filter-spec: spec indicating the size of the image (see below)
  4. version: integer, version of the image. Only used to invalidate the cache and not actually meaningful
  5. slug: slug of the image

Example:

/images/Uo5gv5k9XXsTt6NRHWmGDR4yxC4=/13/width-400/1/chicken-pox.jpg

Signature

HMAC(K, m) where:

  1. K: shared private key only used for image signatures. See settings.IMAGE_SIGNATURE_KEY
  2. m: the string <image-id>/<filter-spec>/ e.g. 1/width-800

Filter Spec

Specifies the size of the image returned. Possible values (100 and 200 are example values):

  1. width-100: width 100 and variable height
  2. height-200: height 200 and variable width
  3. min-100x200: variable width and height but trying to keep the values at least 100x200
  4. max-100x200: variable width and height but trying to keep the values at most 100x200
  5. fill-100x200: crops the image so that the final size is exactly 100x200
  6. original: original size