Introduction

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 need of 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 checkout the video below.

How to download and install postman in windows

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 http protocol or http request.

Structure of http request (Source: https://zapier.com/learn/apis/chapter-2-protocols/

URL - Used to identify the 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 - Provide 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 Oxford Dictionaries API, which allows you to check word meanings among many other functions.

We will test the functionality of getting a meaning of a word, which requires the following information (see here):

URL endpoint: https://od-api.oxforddictionaries.com/api/v2/<endpoint>/<language_code>/<word_id>

Headers: app_id and app_key

Method: GET

Body: No data

app_id and 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

  1. Download and install Postman.
  2. Access Oxford Dictionaries API, create an account (by clicking on GET YOUR API KEY) and generate your app id and api key.
  3. Open Postman and create a new request.
  4. 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, eat.
  • We have added 2 header entries, app_id and app_key
  • 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 a wrong  app_key

With wrong app_key, the response is just text, Authentication failed, with a response status code, 403 Forbidden.

ii) Misspell the word - instead of eat, we write ea.  

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 body and query string

Some requests may have a body formatted as JSON or form data, including a query string.

Let us think of a fictitious request, with the following requirements

URL: https://od-api.oxforddictionaries.com/api/v2/entries/enus/rest?status=false

Method: POST

Headers: api_key

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 params

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.

Conclusion

In this walk-through, we have demonstrated how one can test an API using Postman. Postman has many other functions, which you can learn by digging deeper into the official documentation.

Our next article will be a walk-trough on how to document your API using Postman. If you liked this article, you can subscribe and leave comments or questions.

See you in my next Postman walk-through.

You've successfully subscribed to Decoded For Devs
Welcome back! You've successfully signed in.
Great! You've successfully signed up.
Your link has expired
Success! Your account is fully activated, you now have access to all content.