Overview

Use this API alongside our tutorials to teach yourself how to connect to our RESTful APIs. You can:

• get a response from an open-access endpoint, where the calling application and the end users are not authenticated
• get a response from an application-restricted endpoint, where the calling application is authenticated but the end user is not authenticated
• get a response from a user-restricted endpoint, where the calling application and the end user are authenticated

For further details, see the 'Security and authorisation' section below.

API status and roadmap

This API is for learning purposes only and is available in the sandbox environment. To see our roadmap, or to suggest, comment or vote on features for this API, see our interactive product backlog. If you have any other queries, please contact us.

Technology

This API is RESTful.

Network access

This API is available on the internet and, indirectly, on the Health and Social Care Network (HSCN). To use this API with NHS smartcards (see below) you do need an HSCN connection, although internet-facing alternatives are available. For more details see Network access for APIs.

Security and authorisation

This API demonstrates the different authentication methods used in our APIs.

Open-access authentication

Use the hello world endpoint to get a response from an open-access API. Some of our APIs are open-access, which means:

• we do not authenticate or authorise the calling application
• we do not authenticate or authorise the end user - they might not even be present We generally use open-access APIs for public data, where security is not a concern. Our open-access APIs are generally RESTful APIs. For more details on how to access them, see our open-access REST API tutorial.

Application-restricted authentication

Use the hello application endpoint to get a response from an application-restricted API. This access mode is application-restricted, meaning we authenticate the calling application but not the end user. You can use this access mode as follows:

• attended (end user present) - in which case, you must ensure the end user is authenticated and suitably authorised locally by the calling application To use this access mode, use the following security pattern:
• Application-restricted RESTful APIs - API key authentication

User-restricted authentication

Use the hello user endpoint to get a response from a user-restricted API. Some of our APIs are user-restricted, which means:

• we authenticate and authorise the calling application
• we authenticate, but do not authorise, the end user Although we do not authorise the end user, we do generally require the calling application to do it locally. We only support authentication of healthcare workers.

Environments and testing

Sandbox testing

This API is for learning purposes and is only available in our sandbox environment. Our sandbox environment:

• is for early developer testing
• only covers a limited set of scenarios
• is stateless, so it does not actually persist any updates

For more details on sandbox testing, or to try out the sandbox using our "Try this API" feature, see the documentation for each endpoint. Alternatively, you can try out the sandbox using our Postman collection:

Endpoints