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:
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
| Environment |
Base URL |
| Sandbox |
https://sandbox.api.service.nhs.uk/hello-world |
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
Get a "Hello world!" response from an open-access endpoint
Overview
Use this endpoint alongside our open-access REST API tutorial to learn how to connect to our APIs.
Response
HTTP status: 200
Successful response.
Body
Content type: application/json
Example
{
"message" : "Hello world!"
}
|
object
|
|
|
message
string
|
Example: Hello world!
|
Get a "Hello application!" response from an application-restricted endpoint
Overview
Use this endpoint alongside our application-restricted REST API tutorial to learn how to connect to our APIs.
Request
Headers
| Name |
Description |
apikey |
String
API key to authenticate with. Use a valid value for the Sandbox environment.
Required
|
Response
HTTP status: 200
Successful response
Body
Content type: application/json
Example
{
"message" : "Hello application!"
}
|
object
|
|
|
message
string
|
Example: Hello application!
|
HTTP status: 401
Missing or invalid API Key
Body
Content type: application/json
Example
{
"message" : "Invalid ApiKey"
}
Get a "Hello user!" response from a user-restricted endpoint
Overview
Use this endpoint alongside our user-restricted REST API tutorial to learn how to connect to our APIs.
Request
Headers
| Name |
Description |
Authorization |
String
(^Bearer\ [[:ascii:]]+$)
An OAuth 2.0 bearer token.
Example: Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM
Required
|
Response
HTTP status: 200
Successful response
Body
Content type: application/json
Example
{
"message" : "Hello user!"
}
|
object
|
|
|
message
string
|
Example: Hello user!
|
HTTP status: 401
Missing or invalid OAuth 2.0 Access Token
Body
Content type: application/json
Example
{
"message" : "Invalid access token"
}