APIs enable two systems to communicate with each other. For this reason, APIs are very important in today’s system design. Before an API is open for integration, it must be tested thoroughly. Equally, before you embark on integrating any API into your application, it is imperative that you understand the API.
It will be expensive to develop a separate system to be used to test the developed API. Additionally, an API must be documented. Therefore, there is a need for a cheap and easy system to test APIs. This is where Postman comes in handy.
What is Postman?
Postman is an API client system, which is used by software engineers to create, test and document APIs. Postman allows API designers to construct and save complex HTTP calls, reading responses and saving the response formats for the purpose of documentation. Postman can be used by individual users and big organisations.
Postman can be downloaded from their official website and it should be easy to install in windows. If you have trouble installing Postman, you can check out the video below.
Executing APIs using Postman – Steps
In this tutorial, we will need a working RESTful API, whose endpoints will be tested. Before we outline the steps of executing the API endpoints, we will need to say something about the structure of the,
http protocol which HTTP requests and responses implement.
The diagram below summarises the components of the HTTP protocol or HTTP request.
URL – Used to identify the server resource a request is reaching to, but it can also carry data sent to a server as part of the
url or query string.
Method – It tells the server what type of action that needs to be performed – the most common options are GET, POST, DELETE and PUT
Headers – Provides additional information about the request. There are standard headers but you can specify more custom headers.
Body – This is the part, which contains the data that needs to be sent to the server.
Notice that the difference between
http request and
http response is that the latter has a
status code, you can learn more about http status codes here.
Which API are we going to test?
We will test the Oxford Dictionaries API, which allows you to check word meanings among many other functions.
We will test the functionality of getting the meaning of a word, which requires the following information (see here):
app_key are obtained from the API and are used for authentication. The API specifies that these two pieces of information are passed to the server as part of the headers.
language_code (the word language)and
word_id (word whose meaning is needed) are sent to the server as part of the URL.
API testing steps
- Download and install Postman.
- Access Oxford Dictionaries API, create an account (by clicking on GET YOUR API KEY) and generate your
- Open Postman and create a new request.
- Fill out the request as shown below and click Send.
Observe the following:
- The URL is
https://od-api.oxforddictionaries.com/api/v2/entries/en-us/eat, which also specifies the word whose meaning is needed,
- We have added 2 header entries,
- This request does not have any data in the body
- The http response has a JSON data response as its body
- The http response has a status code, which is
200, which is a success
Let us see what the response will look like when we make requests as follows:-
i) Use the wrong
app_key, the response is just text,
Authentication failed, with a response status code,
ii) Misspell the word – instead of
eat, we write
There is no English word like
ea, and therefore, the response status code is
404 for NOT FOUND, also called
resource not found.
iii) Make a request but the
app_id is missing in the headers.
Notice that we unchecked
app_id in the headers, so it will not be sent to the server with the request. Such a request will not be valid. The API’s response has a status code of
403 with text response body,
Authentication parameters missing.
Sending a Postman request, which includes a
Some requests may have a body formatted as
form data, including a
Let us think of a fictitious request, with the following requirements
Body:full_name and address
The request described above will be build as shown below. Notice that the query string,
status, is added to Postman as
The query string is added as a param and it appears on the URL.
The api key is added as part of the header.
Data to be passed along with the request is put in the body section.
If required, the body data can be passed in form of JSON. For instance, it could be passed as a JSON object as shown below.
Our next article will be a walk-through on how to document your API using Postman. If you liked this article, you can subscribe and leave comments or questions.
See you at my next Postman walk-through.