Using the API

This page is for account holders wanting to automate the download of release files.

Introduction

The API provides endpoints to:

• list available releases of an item
• download a release file via a URL provided by the list endpoint

These endpoints are:

• secure – API requests and responses are over HTTPS
• reliable – downloads from the website have been via the download endpoint since September 2019
• available to all account holders
• synchronised with account subscriptions – anything an account holder can download from the website can be downloaded through the API

API key

Each account has a unique API key based on the account’s primary email address and password. If either change, a new key is generated and the old key is disabled.

The API key for an account is shown on the account management page.

Please do not share account API keys.

Release list endpoint

Request

A request to this endpoint is an HTTP GET of a URL that looks like this:

Replace deadc0de with the API key, and 123 with the item number.

Item numbers can be found in the URLs of releases pages. For example, the URL for the NHS National Interim Clinical Imaging Procedures releases page is:

In this example the item number is 14.

Request only the latest release by adding ?latest to the URL, like this:

Successful response

A JSON object containing a superset of the information available on the releases page of the requested item, including URLs of release files.

The releases appear in the same order as on the releases page, from new to old.

Here is an example response:

{
  "apiVersion" : "1",
  "releases" : [ {
    "id" : "DIAGIMG_29.0.0_20200401000001",
    "name" : "Release 29.0.0",
    "releaseDate" : "2020-04-01",
    "archiveFileUrl" : "https://isd.digital.nhs.uk/download/api/v1/keys/deadc0de/content/DIAGIMG/29.0.0/NHS_DIAGIMG/nhs_diagimg_29.0.0_20200401000001.zip",
    "archiveFileName" : "nhs_diagimg_29.0.0_20200401000001.zip",
    "archiveFileSizeBytes" : 4818612,
    "archiveFileSha256" : "36DBA10E5708B0CBCFAE07F977E83635E20A8592E1DB26D6BBBF2587A8997BA5",
    "archiveFileLastModifiedTimestamp" : "2020-04-02T10:47:42.000Z",
    "checksumFileUrl" : "https://isd.digital.nhs.uk/download/api/v1/keys/deadc0de/content/DIAGIMG/29.0.0/NHS_DIAGIMG/trud_nhs_diagimg_29.0.0_20200401000001.xml",
    "checksumFileName" : "trud_nhs_diagimg_29.0.0_20200401000001.xml",
    "checksumFileSizeBytes" : 174,
    "checksumFileLastModifiedTimestamp" : "2020-04-02T10:53:28.000Z",
    "signatureFileUrl" : "https://isd.digital.nhs.uk/download/api/v1/keys/deadc0de/content/DIAGIMG/29.0.0/NHS_DIAGIMG/trud_nhs_diagimg_29.0.0_20200401000001.xml.asc",
    "signatureFileName" : "trud_nhs_diagimg_29.0.0_20200401000001.sig",
    "signatureFileSizeBytes" : 484,
    "signatureFileLastModifiedTimestamp" : "2020-04-02T10:53:36.000Z",
    "publicKeyFileUrl" : "https://isd.digital.nhs.uk/download/api/v1/keys/deadc0de/content/public-keys/trud-public-key-2013-04-01.pgp",
    "publicKeyFileName" : "trud-public-key-2013-04-01.pgp",
    "publicKeyFileSizeBytes" : 1736,
    "publicKeyId" : 6
  } ],
  "httpStatus" : 200,
  "message" : "OK"
}

Error responses

If the API key is invalid:

{
  "apiVersion" : "1",
  "httpStatus" : 400,
  "message" : "BAD REQUEST"
}

If the item number is invalid:

{
  "apiVersion" : "1",
  "releases" : [ ],
  "httpStatus" : 404,
  "message" : "NOT FOUND: No releases found for API key deadc0de, item 9999."
}

If the requesting account is not subscribed to the requested item:

{
  "apiVersion" : "1",
  "releases" : [ ],
  "httpStatus" : 404,
  "message" : "NOT FOUND: No releases found for API key deadc0de, item 123."
}

Release download endpoint

Request

A request to this endpoint is an HTTP GET of a URL provided in the JSON response of a previous release list endpoint request, and looks like this:

Successful response

The requested release file.

Error responses

All error conditions result in an HTTP 404 error response.

Automation

Run automation scripts during UK office hours, or between midnight and 5am UK local time to avoid conflict with maintenance activities.

Below are sample scripts that use the API to automate downloads. The scripts assume that there is a valid API key in environment variable TRUD_API_KEY.

Bash

trud-api-download-release.bash

PowerShell

Get-TrudRelease.ps1