Skip to main content
Testing APIs

Learn about the environments we provide to test your software with our APIs.

Overview

We provide environments to test your software with our APIs. There are different environments depending on which APIs you are using.

For some of our APIs, you must give evidence of your testing before you go live as part of our onboarding process.

This page includes some general information, but to find out about testing a particular API, read its documentation in our API catalogue.


Sandbox testing

Some of our APIs have a sandbox environment you can use for learning, experimentation and early testing.

Sandbox APIs are open-access, don't usually require authorisation and are usually stateless - they return hard-coded responses.

To see which of our APIs have a sandbox, see our API catalogue, filtered to show APIs with sandboxes.


Integration testing

Some of our APIs have integration test environments you can use for more realistic testing.

The different approaches to integration testing are explained below. For details on a particular API, read its documentation in our API catalogue.


Integration testing with our RESTful APIs

Some of our RESTful APIs have test environments you can use for more realistic testing than is possible in a sandbox.

These include:

  • the external development environment (DEV) - for early development testing of a few specific APIs, including authorisation and authentication testing with NHS login, or API-specific testing tools
  • the integration test environment (INT) - for integration testing of most APIs including authorisation, release and assurance testing

Their base URLs are:

Environment Base URL Availability
DEV https://dev.api.service.nhs.uk/ Limited to specific APIs
INT https://int.api.service.nhs.uk/ Available with most APIs

You can access our development and integration test environments as follows:

1. Create an application and activate APIs

  1. If you don't already have one, create a developer account.
  2. Navigate to my developer account and sign in.
  3. Select 'My applications'.
  4. Select '+ NEW APP'.
  5. Enter details for your application. You can share one application between development and integration test environments.
  6. In the 'APIs' section, find the testing APIs you want to test with and activate them by clicking the slider.
  7. If you are using user-restricted APIs, specify your application's OAuth 2.0 Callback URL.
  8. Select 'CREATE' to create the application.
  9. Make a note of the API key and secret.

2. Generate a key pair, if required

If you are using signed JWT authentication, you need to generate a private/public key pair for testing and register your public key with us.

For details, see Application-restricted RESTful APIs - signed JWT authentication.

3. Configure your software for testing

To get your software working with our integration test environment, configure the following:

  1. Base URL for APIs: development dev.api.service.nhs.uk/ or integration int.api.service.nhs.uk/
  2. OAuth client ID and client secret (if needed): use the API key and secret from the previous step
  3. Base URL path for our authorisation server (if needed) as follows:
Type of testing Environment Availability Authorisation server base URL Paired CIS2 or NHS login environment
Application-restricted API - signed JWT authentication Development Limited to specific APIs dev.api.service.nhs.uk/oauth2 Not applicable
Application-restricted API - signed JWT authentication Integration All APIs  int.api.service.nhs.uk/oauth2 Not applicable
User-restricted API - simulated NHS Care Identity Service 2 sign-in - no smartcard needed - use for early testing Integration All APIs int.api.service.nhs.uk/oauth2-no-smartcard Not applicable
User-restricted API - NHS Care Identity Service 2 sign-in with smartcard or modern alternative Integration All APIs int.api.service.nhs.uk/oauth2 CIS2 Integration (INT)
User-restricted API - simulated NHS login sign-in Development Limited to specific APIs dev.api.service.nhs.uk/oauth2-no-smartcard Not applicable
User-restricted API - simulated NHS login sign-in Integration All APIs int.api.service.nhs.uk/oauth2-no-smartcard Not applicable
User-restricted API - NHS login sign-in with username and password Development Limited to specific APIs

dev.api.service.nhs.uk/oauth2

NHS login Sandpit
User-restricted API - NHS login sign-in with username and password Integration All APIs int.api.service.nhs.uk/oauth2 NHS login Integration

4. Set up smartcard access, if required

If your software is using smartcards for user authentication, do the following:

  1. get an ODS code - you’ll need one before you can access the Health and Social Care Network
  2. get access to the Health and Social Care Network
  3. get physical smartcards for testing
  4. download client software, including the Identity Agent (IA) and NHS Credential Management software (previously known as NHS Identity Hub)

You must use a Windows platform with your software, including the .NET framework.

To see which versions of Windows operating systems and browsers are supported, see Supported operating systems and browsers.

To download Identity Agent and NHS Credential Management software over your HSCN connection, see Configurations recommended by Care Identity Authentication.

5. Set up test data, if required

Some of our APIs include standard test data packs.

In some cases you might need to set up your own test data, for example:

  • to test specific cases that the standard test pack doesn't cover
  • to test data updates, for example patient data in PDS

To set up your own test data, you can either:

  • use our Test Data Self-Service Portal (TDSSP) test data tool - but you need an HSCN connection - or
  • contact us to set up test data for you

To request access to our Test Data Self-Service Portal (TDSSP):

  • contact us at testdata@nhs.net for the URL, username and password you’ll need to access the tool

  • tell us if you need access to a specific test pack for update testing, for example, for PDS update testing we recommend the PDS Compliance Pack

For more details, contact us.

6. Start testing

During testing, for user-restricted APIs you need to sign in as an end user, as follows:

  • if your test environment is set up for smartcard access, use the smartcard you set up in step 3 above
  • if your test environment is set up for simulated sign-in, simply click the 'sign in' button - you don't need any credentials

Integration testing with our HL7 V3 APIs

Our HL7 V3 APIs have a number of Path to Live environments for integration testing, including:

  • Development - early sandbox testing
  • Integration - end-to-end and regression tests
  • Deployment - test in situ and user acceptance tests
  • Proof of concept
  • Non-functional tests

For more details see Path to Live environments.


Performance testing

We do not provide environments for performance testing.

Moreover, the path-to-live environments for our RESTful APIs have low rate limits to protect them against overuse.

Last edited: 17 September 2021 11:46 am