API Building and Testing Made Easier with Postman

Thanks to Jeff Smith for kindly helping to peer review this article.

Trending posts on SitePoint today:

• What is HTTP/2?
• Tame Unruly Style Sheets With These Three CSS Methodologies
• Your Regular WordPress Maintenance Checklist
• Shared Server Hosting: the Pros and Cons
• Why Every Website Needs HTTPS

An API (application programming interface) is a medium of interaction between applications. APIs that use HTTP or HTTPS are called Web APIs.

If you look around on the Internet, a large number of services use APIs. Anything with a social login uses an API; the mobile application of an ecommerce site uses an API; even the ads that you see on the Internet use APIs!

By creating an API for your service, you enable third-party developers to create applications based on your service. For instance, the social newspaper Frrole uses the Twitter API to generate contextual insights by analyzing a large volume of tweets.

Assuming you have assessed the pros and cons of creating an API, let’s talk briefly about the process of creating and testing APIs.

Creating APIs

Although there are many ways of creating an API, a Web API is created using the REST (Representational State Transfer) framework. The REST framework states a set of guidelines that one must follow while creating an API. With the large number of APIs being created daily, it serves as a standard for Web-based APIs.

The four most common actions performed through APIs are view, create, edit and delete objects. The REST framework maps four HTTP verbs to these actions: GET, POST, PUT and DELETE. There are many verbs that have been added to this list like PURGE and PATCH, but in this article, we’ll talk about only the four basic ones. This article on the best practices for a pragmatic RESTful API, by Vinay Sahni, founder at Enchant.com, may be useful for a first-time developer.

Nowadays, there are many frameworks that provide wrappers over the basic HTTP layers, thus making your life as a developer easier. All you need to do is invoke the required commands or functions and focus on the functionality. Popular examples include Slim and Toro, two PHP-based micro frameworks that help you create REST APIs quickly.

Testing APIs through the CLI

The prime motive of creating an API is to enable other applications (which may be yours or developed by third parties) to use the services. Therefore, at every stage of the API development process, a critical part is testing the API for functionality, exception handling and security.

Using an API involves a request to the required resource (usually a URL) using one of the verbs (or methods). You may have to add headers depending on the requirements of the API you’re using. One way to request such a resource is through the command line.

In this post, we’ll concentrate on four parts of an API call – the URL, the HTTP verb, the headers and parameters. We’ll use the cURL library to send requests to the API resources through the CLI. cURL is a command line tool that helps in transferring data with URL syntax – supporting FTP, FTPS, HTTP, HTTPS.

Let’s look at the following command:

curl -i -X POST -H 
    "Content-Type:application/json" 
    http://www.my-api-example.com:port/ -d 
    '{"Name":"Something"}'

The -i command stands for include, which tells the command that headers are present in the request. The -X option is immediately followed by the HTTP verb or method. -H specifies custom headers that are added to the request. Finally, the -d option specifies custom form data to be passed along with the request.

The result of an API call is an HTTP response, usually encoded in the JSON format. The response is coupled with an HTTP response code, which gives information about the status of the request (like 200 for OK, 404 if the resource does not exist, 500 if there’s a server error and 403 if the resource is forbidden). For instance, the following response could be sent as a result of the earlier request, along with a 200 status code:

{"message":"success","id":"4"}

Testing such responses within the command line poses a challenge too, especially if the responses have a large number of options.

A list of CLI options while testing APIs are listed in this detailed guide by Codingpedia.

Make Testing Easier with Postman

Postman is an API development suite with powerful features that make the process of API development quick and painless. It’s available as a Chrome extension and as a native app for Mac, Windows and Linux. More than a million developers have given it a try. To install the Chrome extension, you need to first install Chrome, and head over to the project page on the Chrome Web Store.

Let’s first look at how we can emulate our previous CLI request through Postman. The following images show the creation of an API call in Postman with all the four parts discussed above:

The responses that you receive through your requests may also be viewed in the raw or pretty forms, in addition to a preview if the response is in HTML. The following image shows different ways of viewing a response in Postman:

Postman automatically saves the API calls you’ve made in the past, which saves time while testing APIs. Further, they can be grouped into related API calls for your convenience. Here’s an example of a history of API calls through Postman:

Using the Facebook Graph API through Postman

A good way of demonstrating how Postman works is through the Facebook Graph API. In this post, we’ll focus on the posts on a user’s timeline, how to view details of a post, and finally how to create and delete a post.

The access token is of utmost importance while using the Graph API. There are many permissions associated with a token. For instance, you can create a post using the token only if publish_actions was one of the selected fields while the token was generated. This added level of security helps you grant specific actions to a given app while logging in through Facebook.

View Posts

To send requests to the Graph API, you need to generate an access token. Once you have generated a token, you should send a GET request to the following URL with the access_token as a parameter:

GET /me/

The picture below shows a basic Graph API call with your details:

You can check the list of posts on your timeline through the following command:

GET /me/feed/

Here’s how the details of the list of posts on your timeline might appear:

To view the details of a single post, the following resource is used:

GET /post-id/

The details of a single post look like this:

Like a Post

To like a post, simply send a POST request to the following URL (do note that publish_actions are required to like a post):

POST /post-id/likes/

Sending a like request through Postman looks like this:

Similarly, you can delete a like by sending a DELETE request to the same URL:

DELETE /post-id/likes/

Create Posts

To create a post, you need to send a few parameters in addition to the POST request. You need publish_actions to perform this action too.

You can add the following options to your POST request:

• message: a message associated with the post
• link: a link to an external resource
• place: a place associated with the post (analogous to checking into a place)
• tags: to any friends or pages
• privacy: the audience that the post is visible to
• object_attachment: of any existing Facebook post

The documentation explains the use of all these features.

You can create a post on your timeline or that of a user, page, event or group according to the URL that you choose to send the request to:

POST /me/feed/
POST /user-id/feed/
POST /page-id/feed/
POST /event-id/feed/
POST /group-id/feed/

Let’s try posting on our own timeline. If the request is successful, we’re given the ID of the post that was created. Here’s an example of creating a new post using the Graph API:

To edit a post, you need to send a POST request (not a PUT) to the following URL with the same parameters with which a post is created:

POST /post-id/

Deleting a Post

Just like deleting a like, deleting a post requires you to send a DELETE request to the post URL:

DELETE /post-id/

Note: we’ve seen in this article that Postman has a lot of useful features. There are many more features – like running a collection of APIs on multiple data values – that are available after upgrading from the free version ($9.99 for a single license).

Conclusion

Creating an API is a crucial task, which involves many important steps. Postman makes the process of thorough testing easier. As of now, Postman seems to solve the general developer’s problems well. However, it remains to be seen how it evolves with the paradigm shifts that are common in the web industry.

Did we miss an important feature of Postman? Do you use a different client for testing APIs? Do let us know in the comments below.

Frequently Asked Questions about API Building and Testing with Postman