Getting started with Postman

Published on 15 June 2023 by Andrew Owen (4 minutes)

I’ve written about REST APIs before, but up until now I haven’t covered the easiest way to get started interacting with them. Created by Abhinav Asthana in 2012 as a side project to simplify API testing, Postman now has more than 25 million registered users. I’m assuming you already know about REST APIs. But if not, I’ve got an introductory article on the subject.

Postman is available as a web app or as a download for Linux, macOS and Windows. I prefer to use the desktop app. Whichever you choose, the first thing you need to do is create a collection. This is a portable set of data about the API you’re interacting with, including authorization, URLs and endpoints. If the API you want to use has a Swagger or OpenAPI schema, then the easiest way to create a collection is to import the schema.

In the main menu, select File > Import and drag your schema file over the dialog. Select Postman Collection and click Import. If you want to modify the API, then you can select OpenAPI with a Postman collection. But for the purposes of this article, I’ll stick to using an existing schema. If you don’t have a schema, then you’ll need to create a collection with File > New > Collection.

If you’ve imported a schema, then a lot of the configuration will already be done for you. But, if you’ve created a collection from scratch, then you should start by clicking Add request in the collection’s Actions ( … ) menu. Click the collection’s Variables tab to edit global variables. If they don’t exist already, create a variable called baseUrl with the value https://{{instance}}.example.com/api/v2 where example.com/api/v2 is the path to the API. Then create a variable called instance with the subdomain. For public APIs there may only be one subdomain.

If you’re creating the collection from scratch you can now use {{baseUrl}}/endpoint/ as the URL for each method, where endpoint is the API endpoint you want to connect to. For example, {{baseUrl}}/search/. If you imported a schema, these should be pre-populated.

The next thing to do is to configure authorization in the collection’s Authorization tab. Public APIs may not require authorization, in which case you can select No Auth from the Type list. The next most common type of authorization is Basic Auth. This takes the form of a Base64 encoded Username and Password (separated by a colon in the HTTP request header).

But, you may have to deal with an API that encodes username:password as a single string. If so, then you’ll have to do the Base64 encoding yourself. On Linux and macOS you can encode and decode Base64 with echo "username:passowrd" | base64 and echo "BASE64_ENCODED_STRING" | base64 -D respectively. With Windows PowerShell the encode command is:

[System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("username:password"))

and the decode command is:

[System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String('BASE64_ENCODED_STRING'))

In the collection’s Authorization tab, select No Auth. Then in the Pre-request Script tab, add:

pm.request.headers.add({
  key: "Authorization",
  value: "Basic BASE64_ENCODED_STRING"
});

This adds the header to every request in the collection.

Now, if you’ve imported a schema, you can start trying out the endpoints. In the collection, click an endpoint to see its settings. The API docs should tell you which Params are required and what content is valid in the Body. You can complete these in the tabs. Parameters are a key/value pair. The Body may be plain text, JavaScript, HTML or XML. But most commonly it’s JSON. Postman give you the option to apply various formatting to the body content.

If you imported a schema, the body should be pre-populated. If not you should be able to copy paste the example code from the API docs. One note of caution is that if you save your changes you will replace whatever the default was. Postman is an incredibly powerful tool and it’s well beyond the scope of a blog article to get into the detail. So your next stop for more information should be the Learning Center.