Testing API with Postman

In this post we talk about problems associated with testing APIs and some solutions, constructing HTTP requests, and analyzing responses. For this purpose there is a tool called Postman. Postman is an app for developers (and casual users) and has some very useful features. There are a few things to watch out for when using Postman so we'll be sure to go over those. In this post we discuss Postman version 2.0.5.

What is Postman

Postman is a Google Chrome app that helps you create, save, and send HTTP requests and test response data. This isn't a comprehensive list of its features, but we're going to take a deeper look at a subset of them. We’ll focus on the main features of Postman, but first let's clarify why you might need Postman.

Why you need it

When working with an API you must be sure it works as expected. A great way to determine this is by writing integration tests. The best practice is to write tests before writing the implementation code. If you use the right tests and have high code coverage, it is a good indicator that you’ve got good quality code that meets your business requirements. But in reality, not all API implementations are covered by internal integration tests. There are several cases when you might want to write external integration tests to make sure your APIs work as intended:

  • There is no good testing framework to use with the technology you have on your API backend
  • You have to modify a working API whose implementation isn't covered with tests
  • You delegate writing APIs to another team and you are not sure that their implementation will be covered by tests

Note that all of these cases indicate that something is wrong with your development process. There could be poorly chosen technology, bad decision-making, or the team you picked for the task isn't the right one. But in the real world sometimes it’s better to choose the faster and easier solution even if it adds more complexity to the entire system.

Alternatives

Of course there are various other options for testing APIs but most of them are either manual or they are not scalable.

Let's assume you have a working API and the documentation that describes how to use it. You can start testing it with Curl because it’s fast and easy to write a command in the console specifying just the url and parameters.

curl 'https://api.yourdomain.com/brands?take=3'  

If you need to send several different requests or you need to modify and repeat requests it turns out that this method isn’t very fast or useful. However, there are more advanced tools that come in handy in this case. Consider using a tool like Charles. Specify the proxy parameter in a Curl command and you can catch your requests sent from Curl inside Charles.

curl -x 192.168.0.98:8888 'https://api.yourdomain.com/brands?take=3'  

This will help you see all the information about HTTP requests and responses such as body and headers.

charles

It also provides additional features such as making connection throttling, editing, saving, and request opening. It’s useful but it’s not good enough when you need to organize your requests and work with test response data in several different environments.

Postman helps you overcome the aforementioned disadvantages. Let's get started and use it to send your first request.

First request in Postman

Let's use Github API as an example and send a test request to get all closed issues of the Github Markup repository.

postman

You can use collections if you'd like to save requests and be able to quickly repeat or modify them later. Let's create a collection named Github and save the above request into this collection.

postman collection

That's it, now your request is saved and you can continue testing Github API at any time. You can see more examples in the official documentation, but for now let's learn how to test the responses of your API requests.

Testing

There are a lot of things we can test in an HTTP request and its response. For example:

  • Response status code
  • Data values
  • Data format or response object schema
  • Response headers
  • etc.

Let's validate some of these things in our request. Open the Tests editor by clicking on the Tests button. Postman lets you write tests using Javascript. It also provides several response-related variables such as responseBody, responseCode, etc. You can find more information about testing in the documentation.

Let's test the response code first.

tests["Status code is 200"] = responseCode.code === 200;  

Tests run every time you send a request. So now if you send a Closed issues request you can see that your first test was passed in the Tests tab.

Using environment variables

A great feature of Postman is the ability to use environments. An environment is a set of configuration options that you can refer to and use in request urls or parameters. You also can access and modify these options in your tests. The ability to modify environment variables allows you to run a sequence of tests and save state between the requests runs.

Let's create a new environment and name it Github API.

new environment

Select this environment at the top and change your request url and parameter as follows:

use environment variables

Now continue testing Github API and test to see that all issues in response are indeed closed. To access an environment variable use the getEnvironmentVariable method of Postman's global variable postman
and pass the key of the variable you'd like to access into that method.

var issues = JSON.parse(responseBody);  
var closedState = postman.getEnvironmentVariable("closed_state");  
var allIssuesAreClosed = issues.every(function(issue) {  
  return issue.state === closedState;
});
tests["All issues are closed"] = allIssuesAreClosed;  

Testing JSON Schema

Postman provides a way to test the schema of your JSON response data according to JSON Schema Draft v4 specification. Postman uses a Tiny Validator tool for this purpose. It is a powerful tool for validating your JSON response.

Let's test the schema of a JSON response of Closed issues request. To see more details about JSON Schema with examples head over to the official site.

var schema = {  
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type" : "array",
    "items" : {    
        "type": "object",
        "properties": {
            "id": { 
                "type": "integer" 
            },
            "title": { 
                "type": "string" 
            },
            "url": { 
                "type": "string" 
            },          
            "state": { 
                "type": "string" 
            },
            "body": { 
                "type": "string" 
            },
            "user": {      
                "type" : ["null", "object"],
                "properties" : {
                    "id": { 
                        "type": "integer" 
                    },
                    "login": { 
                        "type": "string" 
                    }
                },
                "additionalProperties": true,
                "required": [ "id", "login" ]
            },
        },
        "additionalProperties": true,
        "required": [ "id", "title", "state", "body", "user", "url"]
    },
}

tests["Valid issues schema"] = tv4.validate(issues, schema);  
console.log(tv4.error);  

I'd like to point out that referring remote schemas doesn't work in the current version of Postman (2.0.5).

Testing collections

When you finish creating your test requests you probably want to run all the tests at once. For this purpose Postman provides a Collection runner. You just need to specify a collection and an environment and it will run all the requests in a collection in the order in which you set them. It also runs tests for every request and gives you an aggregate summary of what happened.

collection runner

Multipart/form requests

Often when working on and testing an API you need to upload files. One way to do this is to send a file via a multipart/form request. If you have such requests in your collection you will have a problem running them via collection runner. This is because Postman only saves the name of the file that you specified in the editor, and collection runner can't find that file. In order to overcome this issue and send multipart/form requests you have to test them one by one from the editor or run the collection using the command line tool called Newman.

First you need to export your collection and environment into files on the disk. Then you're able to run a command in your terminal.

newman -c github_collection.json -e github_environment.json  

The trick to making multipart/form requests work is to place all the files that are referenced in collection requests into the same directory that you run the newman command from.

Pitfalls of collaboration using Postman

It can be a bit tricky to collaborate with other people using Postman. Of course, you can use a Postman account to share collections with your team. Details of this are described here. But if you want to use a version control system you should be ready to put in extra effort. Postman doesn't work with files on your disk directly, it can only import data from local files or export your collection into a file. So, if you want to organize your workflow on Postman collections using a version control system you have to export and replace the file in the repository manually every time you want to commit changes.

Wrap-up

We've looked these common features that Postman provides:

  • Creating, sending, and saving HTTP requests
  • Analyzing response data
  • Working with environments
  • Writing and running tests
  • Collaborating with your team

Postman works great for most of these cases, but there’s some room for improvement. Nevertheless Postman is a solid product for managing and testing HTTP requests. This definitely warrants your attention if you’re a developer or if you work a lot with APIs.

If you have any questions about Postman feel free to leave a comment below or shoot us an email at info@smartcloud.io, we'd be happy to help you.

__
Alex Petropavlovsky @petropavlovsky.
Editor: Tim Baron.

comments powered by Disqus