Skip to main content
Open-access REST API tutorial

Hands-on tutorial to help you learn how to connect to our open-access REST APIs.

This developer resource is in beta. We welcome your feedback via the feedback widget or by contacting us.

Overview

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

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

In this tutorial we show you how to do this using our example API, Hello World. It explains:

  • using the 'Try this API' feature
  • using Java
  • using .NET (C#)
  • using Javascript
  • using Python

  


Using the 'Try this API' feature

You can call an open-access REST API directly from the API specification page 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 Get a "Hello world!" response from an open-access endpoint. This is an example open-access endpoint.
  3. 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.
  4. Click  on the ‘Try this API’ button. This pops-up a ‘Try this API’ window. Notice that the expandable path header /hello/world... does not show a padlock icon, as this is an open-access endpoint and you do not need to authorise.
  5. Click on the expandable path header /hello/world... in the 'Try this API' window. This expands the section and displays the parameters and a ‘Try it out’ button.

  6. Click on the ‘Try it out’ button. This displays an ‘Execute’ and a ‘Cancel’ button in the expanded section below.

  7. Click on the ‘Execute’ button. This calls the endpoint and displays a ‘Clear’ button next to the ‘Execute’ button. It then displays the request as a CURL command. If all is working well, the response should be 200 OK with a suitable JSON object in the response body.
  8. Optionally, click on the ‘Download’ button on the right-hand side of Response, to download the response as a JSON file.

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:

HelloWorld.java

import java.io.BufferedReader;

import java.io.IOException;

import java.io.InputStreamReader;

import java.io.OutputStream;

import java.net.HttpURLConnection;

import java.net.URL;

 

public class HelloWorld {



    private static String BASE_URL = "https://sandbox.api.service.nhs.uk/hello-world/hello/world";

    public static void main(String[] args) throws IOException {

        URL obj = new URL(BASE_URL);



        HttpURLConnection connection = (HttpURLConnection) obj.openConnection();

        connection.setRequestMethod("GET");

       

        int responseCode = connection.getResponseCode();



        if (responseCode == HttpURLConnection.HTTP_OK) {

            BufferedReader in = new BufferedReader(new InputStreamReader(

                    connection.getInputStream()));

            String inputLine;

            StringBuffer response = new StringBuffer();



            while ((inputLine = in.readLine()) != null) {

                response.append(inputLine);

            }

            in.close();

            System.out.println(response.toString());

        } else {

            System.out.println(

                "GET request not worked, response code: "+responseCode

            );

        }

    }

}
  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 (C#)

To call the API from a C# program:

  1. Launch your favourite C# code editor.

  2. Create a new file called HelloWorld.cs.

  3. Enter the following code into the class file:

HelloWorld.cs

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/hello/world";

 

            HttpClient client = new HttpClient();

            HttpResponseMessage response = await client.GetAsync(url);

            response.EnsureSuccessStatusCode();

 

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

            Console.WriteLine(responseString);

        }

    }

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

Using Javascript

  1. Launch your favourite Javascript code editor.
  2. Create a new script called HelloWorld.js.
  3. Enter the following code into the script:

HelloWorld.js

const url = "https://sandbox.api.service.nhs.uk/hello-world/hello/world"

fetch(

    url,

    {

        method: 'GET'

    }

)

.then(res => res.json())

.then((data) => {

    console.log(data);

})

.catch((error) => {

    console.error(error);

});
  1. Run this script.
  2. If all is working well, the response should be 200 OK with a suitable JSON object in the response body.

Using Python

  1. Create an application using the guide above.
  2. Launch your favourite Python code editor.
  3. Create a new script called HelloWorld.py.
  4. The following code snippet requires the external dependency requests.
    To install requests, run this command in your terminal:
    $ pipenv install requests
  5. Add the following code to your script:

HelloWorld.py

import requests

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

print(response.json())
  1. Run this script.

  2. If all is working well, the response should be 200 OK with a suitable JSON object in the response body.

Last edited: 12 August 2021 10:55 am