Hello World API

Teach yourself how to connect to our RESTful APIs.

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

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

get

/hello/world

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!"
}

Schema

Name	Description
object
message string	Example: Hello world!

Get a "Hello application!" response from an application-restricted endpoint

get

/hello/application

Overview

Use this endpoint alongside our application-restricted 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 application!"
}

Schema

Name	Description
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

get

/hello/user

Overview

Use this endpoint alongside our user-restricted 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 user!"
}

Schema

Name	Description
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"
}