Find and Use an API - Using an API

To explore and use an API, simply:

Sign in with your GOV.UK One Login account here (as detailed in the Creating an account section).
Find the API you wish to use by using the search function (as detailed in the Finding an API section).
Select on the name of the API you wish to use from the search result. This will show you the API details page. The information on this page is grouped into sections depending on the API and the details supplied by the API provider including:

Header - Located at the top of the page with details including:
- API Name
- API description
- API Version
- Release version
- API type
Overview - Gives you a summary of the purpose of the API.
Documents - Gives you information relating to any technical documents supplied by the API provider including:
- Data structure information
- Uploaded schema (JSON Format)
Environments - Gives you information relating to the available environments for the API including:
- Environment (Dev, Staging or Live)
- Base URL
- Action (View or Subscribe)
Operations - Gives you information relating to available operations and URL template for an API including:
- Operation Method (GET, POST, etc)
- Description
- URL template

If you are already subscribed to an API, the Action link within the Environments section will be displayed as View. This means you can view any subscriptions to the API. Else, it will be displayed as Subscribe, meaning you can subscribe to the API.

Managing your subscriptions

To manage your subscriptions, simply:

Sign in with your GOV.UK One Login account here as detailed in the Creating an account section of this guide.
Select the My subscriptions tab within the top navigation menu on the Home page. This will show you the My subscriptions page with a list of all your subscriptions including detail such as:

API (API name)
Subscriptions statistics (including the number of subscriptions and status (Active or Inactive)
Manage Subscription link

Select the Manage subscriptions link. This will show you the API Subscriptions page with the following:

Create subscription link
View API definition link to view API definition details including any uploaded files.
Environment
Status (Active or Inactive)
API Subscription name (given by at the time of creation)
View link to view an API subscription details
Delete link to delete an API subscription.

API subscription details page

This page contains detailed information about an API subscription, grouped into clearly defined sections:

Subscriptions details
Subscription key
Native OAuth Application-flow

Subscriptions details section

This section contains general details about an API subscription including:

Subscription name - given by user
Status
Created date
API name and a Copy link to enable you to copy the API name.
API version
Environment
Base URL (URL to the API location) and a Copy link to enable you to copy the Base URL.

Additionally, within this section of the Subscription details page, you will find the following:

Test API link to delete a subscription.
Delete link to delete a subscription.
Disable link to disable your API subscription.
Change link to change the name of your subscription.

Subscribing to an API

You can subscribe to an API within a specified environment by following these steps:

Find the API you wish to subscribe to by following the steps detailed in the Finding an API section of this guide.
Select the API name. This will show you the API Overview page with details of the API.
Select the Subscribe link next to the relevant environment (Dev, Staging, or Live) within the Environments section.
Enter a name for the subscription in the Subscription name text box to help you identify and differentiate it from others you might create. This is because you can have multiple subscriptions for the same API to different environments or multiple subscriptions for the same API to the same environment.
Enter a justification for your subscription in the Justification for usage text box. This describes why you require the API subscription.
Select the Create subscription button to submit the subscription request. Or the Return to API link to cancel and return to the API Overview page.

If your chosen API environment requires subscription approval before it is activated, there will be a message to tell you that. And upon submission, your subscription request will be reviewed by the API provider and the relevant permission granted. In the case where approval is not required to subscribe to an API environment, a justification will still have to be provided (only for record purposes) and the subscription will be created immediately.

Viewing API subscriptions

You can view your API subscriptions by following these steps:

Select the My subscriptions tab within the top navigation menu on the Home page. This will show you the My subscriptions page with a list of all your subscriptions including detail such as:

API (API name)
Subscriptions statistics (including the number of subscriptions and status (Active or Inactive)
Manage Subscription link

Viewing an API definition

You can view an API definition by following these steps:

Select the My subscriptions tab within the top navigation menu on the Home page. This will show you the My subscriptions page with a list of all your subscriptions including detail such as:

API (API name)
Subscriptions statistics (including the number of subscriptions and status (Active or Inactive)
Manage Subscription link

Select the Manage subscriptions link. This will show you the API subscriptions page.
Select the View API definition link at the top of left of the subscriptions listing. This will show you the API definition including overview, documents, environments, operations, release information and more.

Changing the name of an API subscription

You can change your subscription name by following these steps:

Select the My subscriptions tab within the top navigation menu on the Home page. This will show you the My subscriptions page with a list of all your subscriptions including detail such as:

API (API name)
Subscriptions statistics (including the number of subscriptions and status (Active or Inactive)
Manage Subscription link

Select the Manage subscriptions link. This will show you the API subscriptions page.
Select the Change link located to the right of the subscription name. This will show you the Change subscription name page.
Enter a new name for the subscription in the New display name textbox provided.
Select the Change name button to submit.

The changed subscription name will be reflected immediately. However, the status will shown as 'Update in progress' until the change has fully updated through the system at which point the status changes to 'Active'.

Deleting an API subscription

Select the My subscriptions tab within the top navigation menu on the Home page. This will show you the My subscriptions page with a list of all your subscriptions including detail such as:

API (API name)
Subscriptions statistics (including the number of subscriptions and status (Active or Inactive)
Manage Subscription link

Select the Manage subscriptions link. This will show you the API subscriptions page.
Select the Delete link located to the right of the subscription name for the relevant API environment. This will show you the Delete API subscription page with details including:

API name
API version
Environment
Subscription status.

Select the Delete subscription button to delete that subscription. Or the Return to subscription link to cancel.

Alternatively:

Select the My subscriptions tab within the top navigation menu on the Home page. This will show you the My subscriptions page with a list of all your subscriptions including detail such as:

API (API name)
Subscriptions statistics (including the number of subscriptions and status (Active or Inactive)
Manage Subscription link

Select the Manage subscriptions link. This will show you the API subscriptions page.
Select the View link to the right of the right of the API subscription you wish to test. This will show you the API subscription detail page.
Select the Delete link to the right of the Subscription details section of API details. This will show you the Delete API subscription page with details of the subscription you are about to delete including:

API name
API version
Environment
Subscription status.

Select the Delete subscription button to delete that subscription. Or the Return to subscription link to cancel.

Once the subscription is deleted, any existing integrations using the subscription will be denied access immediately. You will also lose both the Primary and Secondary keys associated with that subscription and the OAuth Client ID relating to for Native OAuth Application-flow. This cannot be reversed, so make sure you want to delete the subscription.

Disabling an API subscription

Select the My subscriptions tab within the top navigation menu on the Home page. This will show you the My subscriptions page with a list of all your subscriptions including detail such as:

API (API name)
Subscriptions statistics (including the number of subscriptions and status (Active or Inactive)
Manage Subscription link

Select the Manage subscriptions link. This will show you the API subscriptions page.
Select the View link to the right of the right of the API subscription you wish to test. This will show you the API subscription detail page.
Select the Disable link to the right of the Subscription details section of API details. This will show you the Disable API subscription page.
Select the Disable subscription button to disable the subscription. Or the Return to subscription link to cancel.

Once a subscription is disabled, any existing integrations using the subscription will stop functioning immediately. And when a subscription is disabled the keys remain within the API subscription details and do not changed. This means all keys remain valid, however any API subscription using that subscription key will stop working. Once, the subscription is re-enabled, it will start working again with those keys within 5 seconds.

Testing an API subscription

You can test your API subscription by following these steps:

Select the My subscriptions tab within the top navigation menu on the Home page. This will show you the My subscriptions page with a list of all your subscriptions including detail such as:

API (API name)
Subscriptions statistics (including the number of subscriptions and status (Active or Inactive)
Manage Subscription link

Select the Manage subscriptions link. This will show you the API subscriptions page.
Select the View link to the right of the right of the API subscription you wish to test. This will show you the API subscription detail page.
Select the Test API link to the right of the Subscription details section of API details. This will show you the API Test suite page with options such as:

Operation endpoint selection dropdown option
Add subscription key checkbox option
Add OAuth token checkbox option
Send button
Request URL textbox
Querystring parameter tab with Key and Value entry textboxes
Response body tab

Select the endpoint for the API operation you want to test from the operation endpoint dropdown list (/Download/, /Echo-Get, /Echo-Post, /List, or /Upload). This will auto-fill the Request URL textbox.
Select the Add subscription key checkbox option if you want to add a subscription key to the request.
Select the Add OAuth token checkbox option, if you want to add OAuth token to the request.
Enter the Key and corresponding Value text, if required for the selected operation's endpoint.
Select the Send button to make the request.

Subscription key section

This section of the API subscription details page contains information about an API's subscription key including:

Instructions - given by the provider on how to use the subscription key
Header name and a Copy link to enable you to copy the header name.
Query parameter name and a Copy link to enable you to copy the query parameter name
Primary key which is your unique default key used to authenticate your request and grant you access to consume an API.
Secondary key which is your unique alternative key which can be used in the absence or failure of a primary key to authenticate your request and grant you access to consume an API.

Below each subscription key is a last generation timestamp to indicate when the current key was generated.

Additionally, within this section of the subscription details page, you will find the following:

a View link to view your API subscription's primary key.
a Regenerate link to generate a new primary key. This can be for a number of reasons including a key being compromised or you simply just want a new key.
a View link to view your API subscription's secondary key.
a Regenerate link to generate a new secondary key. This can be for a number of reasons including a key being compromised or you simply just want a new key.

Native OAuth Application-flow section

This section of the API subscription details page contains information about an API's subscription key for for a naitive applications flow and the process of obtaining a token it including:

Instructions
OAuth token endpoint - This is additional information that needs to be provided as part of the request relating to the endpoint. An example is provided in the Testing an API page using Postman.
OAuth Client ID - This is an unique client identifier. And it cannot be changed.
Primary key which is your unique default key used to authenticate your request and grant you access to consume an API.
Secondary key which is your unique alternative key which can be used in the absence or failure of a primary key to authenticate your request and grant you access to consume an API.
OAuth Scope - This is additional information that needs to be provided relating to the endpoint. An example is provided below on how to do this using Postman.

Below each Native OAuth subscription key is a last generation timestamp to indicate when the current key was generated.

Additionally, within this Native OAuth Application-flow section of the subscription details page, you will find:

a Primary key View link to view your API subscription's primary key.
a Primary key Regenerate link to generate a new primary key.
a Secondary key View link to view your API subscription's secondary key.
a Secondary key Regenerate link to generate a new secondary key.

Once you regenerate a subscription key, any API subscription using that key will stop functioning immediately. This is one of the reasons for having a Secondary subscription key which can be swapped in the place of the Primary key before generating a new Primary key for a interruption free operation. You can rotate between the Primary and Secondary keys are anytime.

Viewing your API subscription Primary key

Select the My subscriptions tab within the top navigation menu on the Home page. This will show you the My subscriptions page with a list of all your subscriptions including detail such as:

API (API name)
Subscriptions statistics (including the number of subscriptions and status (Active or Inactive)
Manage Subscription link

Select the Manage subscriptions link. This will show you the API subscriptions page.
Select the View link to the right of the right of the API subscription you wish to test. This will show you the API subscription detail page.
Go to the Subscription key section of the API subscription detail page.
Select the View link to the right of the Primary key shown as masked text 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'. This will reveal the value of the Primary key and a Copy link to enable you to copy it accurately.

Regenerating your API subscription Primary key

Select the My subscriptions tab within the top navigation menu on the Home page. This will show you the My subscriptions page with a list of all your subscriptions including detail such as:

API (API name)
Subscriptions statistics (including the number of subscriptions and status (Active or Inactive)
Manage Subscription link

Select the Manage subscriptions link. This will show you the API subscriptions page.
Select the View link to the right of the right of the API subscription you wish to test. This will show you the API subscription detail page.
Go to the Subscription key section of the API subscription detail page.
Select the Regenerate link to the right of the Primary key shown as masked text 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'. This will regenerate your new Primary key with a Copy link to enable you to copy it accurately.

It is worth noting that once you regenerate a subscription key, any API subscription using that key will stop functioning immediately. This is one of the reasons for having a Secondary key which can be a substitute for the Primary key before generating a new Primary key for a interruption free operation. You can rotate between the Primary key and Secondary key at anytime.

Viewing your API subscription Secondary key

Select the My subscriptions tab within the top navigation menu on the Home page. This will show you the My subscriptions page with a list of all your subscriptions including detail such as:

API (API name)
Subscriptions statistics (including the number of subscriptions and status (Active or Inactive)
Manage Subscription link

Select the Manage subscriptions link. This will show you the API subscriptions page.
Select the View link to the right of the right of the API subscription you wish to test. This will show you the API subscription detail page.
Go to the Subscription key section of the API subscription detail page.
Select the View link to the right of the Secondary key shown as masked text 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'. This will reveal the value of the Secondary key and a Copy link to enable you to copy it accurately.

Regenerating your API subscription Secondary key

Select the My subscriptions tab within the top navigation menu on the Home page. This will show you the My subscriptions page with a list of all your subscriptions including detail such as:

API (API name)
Subscriptions statistics (including the number of subscriptions and status (Active or Inactive)
Manage Subscription link

Select the Manage subscriptions link. This will show you the API subscriptions page.
Select the View link to the right of the right of the API subscription you wish to test. This will show you the API subscription detail page.
Go to the Subscription key section of the API subscription detail page.
Select the Regenerate link to the right of the Secondary key shown as masked text 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'. This will regenerate your new Secondary key with a Copy link to enable you to copy it accurately.