Background

REST API’s are a popular means of manipulating data. REST API’s use a client-server model. The server is a web server and the client is a Web application or a Python, Perl, Java, .NET, Node.js or COBOL program.

REST is an abbreviation for ‘Representational State transfer’ while API is another abbreviation for ‘Application Program Interface’.

This all sounds complicated and almost intimidating but it’s not. Database developers have been manipulating data using a client (SQL*Plus) from a server (Oracle database) for many years.

A REST API call is simply an HTTP request. This HTTP request normally reads data but can also insert, update and delete data.

REST request

A REST request has four parts

Method

The HTTP method is required and indicates the operation to be performed. The most common types of an HTTP request are:

• GET (Read)
• POST (Write)
• PUT/PATCH (Update)
• DELETE (Delete)

Endpoint

The endpoint is the full URL sent to the Web server. For example, this endpoint lists all the feeds available on GitHub.

https://api.github.com/feeds

Click on the link. Data is displayed. It’s not like a conventional Web site but it’s data.

The endpoint is made up of four elements:

• root-endpoint - https://api.github.com/
• path - feeds
• variables - optional variables introduced with a colon (e.g. ‘:user’)
• query parameters - optional set of name=value pairs separated with a ampersand (e.g. ‘?query1=value1&query2=value2’). Query parameters are used to filter the data returned by limiting the number of records and/or using search criteria.

Headers

Headers are optional and used to supply additional information (credentials, parameters).

Body

Data in the body section is also optional and normally used for a POST, PUT or DELETE requests to insert, update or delete data.

REST response

A REST request will receive a response. This is the data requested or an error code.

The response is usually a data set in JSON format (but could be XML or even an image).

The elements of the response are:

Response Code

The HTTP status code indicates the success or failure of the request. A non-exhaustive list of common status codes are:

• HTTP/1.1 200-299 OK - success
  • 200 OK
  • 201 Created
  • 202 Accepted
• HTTP/1.1 300-399 OK - redirect
  • 301 Moved permanently
  • 302 Moved temporarily
  • 304 Not Modified
• HTTP/1.1 400-499 client error
  • 400 Bad Request
  • 401 Unauthorized
  • 403 Forbidden
  • 404 Not Found
  • 405 Method Not allowed
• HTTP/1.1 500-599 server error
  • 500 Internal Server Error
  • 501 Not Implemented
  • 502 Bad Gateway

Content-Type

Indicates the format of the returned data. For example, for JSON data, this is set to

content-type: application/json; charset=utf-8

Content Length

Indicates the size (in bytes) of the returned data.

where to find REST API’s

Many sites offers API’s to access data. Twitter, GitHub, YouTube, IMDb, Apple Music are popular examples.

These sites often require developers to register and obtain an API key (password) in order to access the service. This is normally free and allows the provider to police the service and guard against denial of service attacks (flooding the server with requests in an effort to bring it down).

Governments and public sector bodies often provide excellent sources of public, freely accessible REST API’s. Some of the subject matter may be a little dry; statistics about Coronavirus, trade quotas, water quality, crime.

Programmable Web includes a searchable directory of API’s.

RapidAPI also offers pointers to several API’s for UK data.

Hello world

The first program I create when learning a new language is always ‘Hello World!’. This is useful as it teaches you the basic syntax, how to compile or deploy the program and it is easy to check it works successfully.

The National Health Service (UK) helpfully makes a REST API available that returns ‘Hello World!’

This endpoint does not require authentication and simply returns ‘Hello World!’.

https://sandbox.api.service.nhs.uk/hello-world/hello/world

There are many REST API clients available and we will use a GUI REST client called Insomnia for this tutorial.

Download and install Insomnia which is available for Linux, Windows and MacOS.

Enter the endpoint into the field labelled ‘GET’ in the middle panel and click ‘Send’.

The right hand panel contains the response from this request. The data returned is in JSON format and contains a single entry containing ‘Hello World!’

The other important fields are the status code of ‘200’ which is displayed in Green and represents a successful call for the GET request.

The elapsed time for this request is quick (255 ms).

Finally, the size of the returned data is ‘32B’ (32 bytes).

Summary

Congratulations ! You have submitted your first REST API request. It’s time to put the kettle on and update your CV.

In the next article, we will build on this knowledge by using REST to create a more useful, real-life scenario.