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.

Page contents

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 PHP

  

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 to populate the 'Response' field. Notice that the expandable path header /hello/world... does not show a padlock icon, as this is an open-access endpoint and authorisation is not required. If all is working well, the response should be 200 OK with a suitable JSON object in the response body.

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 PHP

  1. Launch your favourite PHP code editor.
  2. Create a new script called HelloWorld.php.
  3. Enter the following code into the script:
<?php

$cURLConnection = curl_init();

curl_setopt($cURLConnection, CURLOPT_URL, 'https://sandbox.api.service.nhs.uk/hello-world/hello/world');
curl_setopt($cURLConnection, CURLOPT_RETURNTRANSFER, true);

$message = curl_exec($cURLConnection);
curl_close($cURLConnection);

print_r($message);
  1. Run this script by running php HelloWorld.php
  2. If all is working well, the response should be 200 OK with a suitable JSON object in the response body.

Last edited: 24 November 2023 2:57 pm