Back to all posts

How to Use Postman to Test an API During Development

Posted by Soham Kamani on September 14, 2018

REST APIs have become the new standard in providing a public and secure interface for your service. Though REST has become ubiquitous, it's not always easy to test. Postman, an API development environment, makes it easier to test and manage HTTP REST APIs. Postman gives us multiple features to import, test and share APIs, which will help you and your team be more productive in the long run.

ButterCMS is a service that helps you add a blog or CMS to your website, and provides its own REST API endpoints that allow you to interact with your pages and content fields using any HTTP client of your choice. In this post, I’ll demonstrate how to leverage Postman to test the ButterCMS developer APIs.

Installing Postman

You can download and install Postman from the official website

Once you open the application, you should see the main application window:

Installing Postman

Creating our first request

Now that you have Postman installed, let's start by making a request to the /v2/posts endpoint, whose official documentation you can find here. This API has the following properties:

  • A GET method
  • The url : https://api.buttercms.com/v2/posts/
  • The auth_token query parameter, whose value would be your personal API key. For the purpose of this post, we'll use the API key abc123

 

You can enter these details into the Postman application:

Postman 2

  1. Select the GET method
  2. Add the URL https://api.buttercms.com/v2/posts/ (without the query params)
  3. Click on "Params" to add URL query params
  4. Enter the key-value pair for the auth_token query param. It will then appear in the URL input.
  5. Click on "Send" the run the HTTP request

Once the request executes successfully, you should see the result appear in the window below, along with additional information like the status code returned and the request time:

postman 3

Importing requests

Creating our first request was fairly straightforward, but we can make the process even easier. It's time consuming to enter all the request data when we want to test multiple APIs. Fortunately, Postman lets us import them directly from certain formats (one of those formats being the curl command). The Butter API documentation contains curl commands for each API endpoint. We can copy this command as is, and import it directly into Postman:

Postman request 

    1. Click on "Import" on the top left corner
    2. Select the "Paste Raw Text" option, and paste in the curl command text as is into the text field.
    3. Click on "Import"

    Now, you should see the request filled in, just like we did manually in the previous section. Importing requests in this way can help you get up and running in a jiffy, provided you have the curl commands readily available.

    Exporting requests as code

    After testing and experimenting with your API in Postman, the next step would naturally be to use it in your application. Butter already has client implementations for its API in Ruby, Python, Javascript, PHP, Go, and C#. But, if you want to call its API's using a custom HTTP client in the language of your choice, or in a language not included in the Butter API documentation, Postman has you covered. We can export our HTTP request into many different formats and implementations:

    code snippet

    1. Click on "Code" to see the popup menu
    2. Select the format from the dropdown (which defaults to curl)

    For example, here's the "Go" implementation, which actually has the complete program to execute the HTTP request:

    go implementation

    Collections

    So far, we've learned how to use Postman to test a single HTTP endpoint. In reality though, the ButterCMS API consists of a wide range of API endpoints. We could use the steps discussed previously to test the APIs individually, but that would lead to a lot of repeated effort. Postman collections can help us group these APIs together, and share them with others to make our workflow much faster. Let's start by creating a new collection, and saving the above API endpoint into it.

    Create a new collection by clicking on the "New" button on the top left and selecting "Collection":

    collection

    Now, you can save your existing request into the collection:

    postman - save requests

    Click on the "Save" button. Enter the details and collection into which the request should be saved. You should now see the API saved under the collection you just created:

    save requests

    You can save multiple common APIs under the same collection.

    Adding variables

    Now that all the APIs have been added to the collection, we can extract out a few data points that could potentially change often. One glaring data point is the auth token. Although the auth token is fixed for us, it changes for every user or account. If we want to share this collection with our colleagues, we would have to replace the auth token on every endpoint. Postman helps us get around this by using variables in our collection.

    Variables allow us to to have a single source of truth for common information. To use the auth token as a variable, edit the "ButterCMS API" collection you just created:

    Postman - variables

    Click on "Edit" to open the edit window.

    Postman- edit collection

    Go to the "Variables" tab and add in the auth token as a variable, with the name "auth_token".

    Now, change the name of the auth_token query param to {{auth_token}}:

    Postman- auth token

    Now your request should run like it did before. If you add more APIs to this collection, you can use the "{{auth_token}}" variable instead of actually entering your auth token each time. If your auth token changes, all you have to do is change the value of the variable in the edit menu.

    Exporting your collection

    Once you add requests to your collection, you'll need a way to share it with fellow developers. We can export any collection on Postman as a JSON file by using the collections "Export" option:

    Postman export

    This file can then be imported from any other Postman application, complete with all the variables and settings.

    In fact, the Butter developer APIs have a Postman collection as well:

    Run in Postman

    Conclusion

    Postman is one of those tools that a lot of people know about, most of whom do not use it to its full potential. In this post, we learnt how to get up and running with testing HTTP API endpoints with Postman. The user interface makes it easy for us to create and execute HTTP requests to test these endpoints. The import and export features allow us to obtain and use HTTP requests from multiple sources and programming languages. The presence of collections and variables allow you to share APIs seamlessly without repeated effort (as compared to normal text-based documentation). By using Postman, you can make your team and your development workflow more productive by reducing the time spent on testing and sharing API specifications and endpoints.

    Related Articles