Skip to main content

Tutorials

Hands-on tutorials to help you learn how to connect to our APIs.

This developer resource is in beta. We welcome your feedback to api.management@nhs.net.

Open-access REST API tutorial

This tutorial shows you how to connect to an open-access REST API.

Open-access REST APIs are easy to use. They don't require any kind of authorisation, you just need to make an HTTP request the relevant API endpoint.

In this tutorial we'll show how to do this using our example API, Hello World. You'll learn the following methods:

  • method 1: using the 'Try this API' feature
  • method 2: using Java
  • method 3: using .NET
  • method 4: using Ruby
  • method 5: using Python

Method 1: using the 'Try this API' feature

You can call an open-access REST API directly from the Developer Hub using the 'Try this API' feature:

  1. In a new browser tab, navigate to our Hello World API.
  2. In the left-hand navigation, select /hello/.... This will display the endpoints available in the API.
  3. In the left-hand navigation, select world. This is an example open-access endpoint.
  4. In the main panel, read the API specification. Notice that there are no request parameters and that a successful response is a JSON object containing a single field message.
  5. In the right-hand panel (where it says 'Try this API'), click 'Execute'. This calls the endpoint and displays the response. If all is working well, the response should be 200 OK with a suitable JSON object in the response body.
  6. To see more details, click on the maximise icon to the right of 'Try this API'. You'll be able to see the request as a cURL command or as HTTP, and the response as raw HTTP.

Method 2: using Java

You can call an open-access REST API using your favourite programming language. For example, to call the API from a Java program:

  1. Launch your favourite Java code editor.
  2. Create a new class called HelloWorld.java.
  3. Enter the following code into the class file:
COPY
Java code coming soon (if you want to help, please submit some code to api.management@nhs.net)

Java

  1. Compile and run your Java program. If all is working well, the response should be 200 OK with a suitable JSON object in the response body.

Using .NET

To call the API from a C# program:

  1. Create a C# class with the following code in it:
COPY
using System;

using System.Net.Http;

using System.Text;



namespace HelloWorldAPITest



{

    class Program

    {

        static async System.Threading.Tasks.Task Main(string[] args)

        {

            string url = "https://sandbox.api.service.nhs.uk/hello/world";

            HttpClient client = new HttpClient();

            HttpResponseMessage response = await client.GetAsync(url);

            response.EnsureSuccessStatusCode();

            string responseString = response.Content.ReadAsStringAsync().Result;

            Console.WriteLine(responseString);

        }

    }

}

C#

Using Ruby

To call the API from a Ruby script:

  1. Create a Ruby script with the following code in it:
COPY
Ruby code coming soon (if you want to help, please submit some code to api.management@nhs.net)

Ruby

Using Python

To call the API from a Python script:

  1. Create a Python script with the folowing code in it:
COPY
import requests

response = requests.get("https://sandbox.api.service.nhs.uk/hello/world")

print(response.json())

Python

Application-restricted REST API tutorial

This tutorial shows you how to connect to an application-restricted REST API.

To call an application-restricted REST API, you need to tell the API who the calling application is. You do this by including your application's API key when you call the API.

In this tutorial we'll show how to do this using our example API, Hello World. You'll learn two methods:

  • method 1: using the 'Try this API' feature
  • method 2: using Java

Method 1: using the 'Try this API' feature

You can call an application-restricted REST API directly from the Developer Hub using the 'Try this API' feature:

  1. In a new browser tab, navigate to My developer account.
  2. Sign in to your developer account by selecting 'Sign in' in the top navigation bar.
  3. View your applications by selecting 'My applications'.
  4. Create a new application by clicking the '+NEW APP' button.
  5. Give your new application a name, such as 'Hello World Example Application', and a description, such as 'Application for learning how to call APIs'.
  6. Activate the Hello World API for your application. To do this, further down the page, find the Hello World API and click the slider.
  7. Select 'Create' to create the application. Your new application details will be displayed.
  8. Copy your application's API Key to the clipboard by clicking the 'Copy' icon next to the API key.
  9. In a new browser tab, navigate to our Hello World API.
  10. In the left-hand navigation, select /hello/.... This will display the endpoints available in the API.
  11. In the left-hand navigation, select application. This is an example application-restricted endpoint.
  12. In the main panel, read the API specification. Notice that there are no request parameters and that a successful response is a JSON object containing a single field message. Also notice that the API requires a header called apikey.
  13. In the right-hand panel (where it says 'Try this API'), click 'Execute'. This calls the endpoint and displays the response. Because you haven't specified an API key, you should get a 401 Unauthorised response.
  14. Click the 'AUTHORIZE' button. You should see a pop-up box with authorisation options.
  15. Under the heading 'Api Key Auth: api_key', where it says 'Please select app...', select your new application. If you don't see this option, make sure you are still signed in.

  16. Click 'AUTHORIZE', followed by 'OK'.
  17. Now click 'Execute' again in the right-hand panel. If all is working well, the response should be 200 OK with a suitable JSON object in the response body.
  18. To see more details, click on the maximise icon to the right of 'Try this API'. You'll be able to see the request as a cURL command or as HTTP, and the response as raw HTTP.

Method 2: using Java

You can call an application-restricted REST API using your favourite programming language. For example, to call the API from a Java program:

  1. Sign in to your account and create an application as per method 1 above.
  2. Launch your favourite Java code editor.
  3. Create a new class called HelloApplication.java.
  4. Enter the following code into the class file:
COPY
Java code coming soon

Java

  1. Compile and run your Java program. If all is working well, the response should be 200 OK with a suitable JSON object in the response body.

User-restricted REST API tutorial

This tutorial shows you how to connect to a user-restricted REST API.

Details to follow.

Last edited: 31 March 2020 3:19 pm