Getting started with API’s (part 1)

Application programming interfaces (API’s) are the technical standards different software components use to interact with each other. This spans different libraries communicating with each other within the same piece of software (for example a language API specification), to remote API’s where the communication is over a network in a different data centre.

In the world of software testing, you are most likely to be testing these remote API’s using the familiar HTTP/HTTPS protocols of the world wide web

API’s can be built to be used purely by the product they support – perhaps as a back end service called by front end components on the same system. They are also commonly encountered as services in their own right to allow 3rd parties to integrate with and build applications that utilise them (and perhaps other services) – a familiar example would be one of the many insurance comparison sites – these sites use API’s published by various insurance companies to obtain quotes for each customer based on their details, and then allow the user to select which policy to purchase.

Types of API

Broadly speaking there are two types of remote API a tester will encounter, and while they are actually not identically comparable (and there’s plenty of in depth breakdowns on the various benefits and drawbacks of each), as testers we need only concern ourselves with how they can be tested, as the decision on which one to use has all ready been made. Before the emergence of SOAP and then its successor REST, there were other API like services using remote procedure calls but these are no longer common.

SOAP

Simple Object Access Protocol based API’s use XML as the message format and were the preferred way to implement public API’s in the early history of the internet. SOAP can be described as a protocol although it is commonly used over HTTP for simplicity.

SOAP is like an envelope, encapsulating the data being sent over the network with request messages returning responses.

REST

Representational State Transfer based API’s almost always use JSON as the message format although formats including HTML, plain text and others can be supported. REST is now the most commonly used API, developed to address some of the problems with SOAP, and is not a protocol but an architectural style.

REST is like a postcard – a short, snappy message using HTTP methods such as GET, POST & DELETE to perform the desired actions and receive responses.

Exploring a simple REST API

As REST API’s use HTTP methods and common MIME types such as application/json, text/plain & text/html we can use a web browser to submit GET requests and view the data.

Opening this link: https://jsonplaceholder.typicode.com/posts/1 in a browser will submit a GET request to the sample API service and the returned data (in this example, JSON) is formatted by your browser to make it more human readable.

You can manipulate the URL to request different post numbers, or omit the number to return all posts, or change the URL to return different data such the users, comments or photos as detailed here: https://jsonplaceholder.typicode.com/

Introducing Postman

Web browsers can be used to quickly send a GET request, but there are better tools available to manipulate API’s – one of which is Postman available from: https://www.postman.com/downloads/

Once downloaded, optionally create an account or just click on ‘Skip signing in and take me straight to the app’.

GET requests

To try a simple GET request, click ‘New’ and select ‘Request’. In the ‘Save Request’ form, enter a name – e.g. ‘simple GET’, and click ‘Create Collection’ further down to store your new request – call it ‘API test’. Then click the big orange tick and finally, click ‘Save to API test’.

As this is a very simple request, you now need only enter the request URL, which is https://jsonplaceholder.typicode.com/posts/1 and then click ‘Send’

The response is then displayed in the lower half of the window, with the same data we received when using the browser. However, unlike a browser, Postman has features to send different requests (for example POST & DELETE), however these are not supported by the public test API endpoint we have been using.

POST requests

However, there is an API endpoint that will echo back whatever you POST, so in order to test that, create a new request and change the type to ‘POST’. In the URL, enter: https://postman-echo.com/post. In the ‘Body’ tab, click the drop down arrow next to ‘none’ and select ‘raw’. In the text box enter some text, and then click ‘Send’. In the lower half of the window, the response will be displayed as before, and the data you sent should be displayed within the response body (amongst other things).