No, we’re not talking about the person who delivers your mail. We are talking about one of the best, if not the best, tools for creating, and testing APIs. API documentation with Postman is exceptional and efficient. Postman also allows collaboration among team members. The best part? This is all included in the free version!
Postman does offer paid versions with their Basic, Professional, and Enterprise versions. We won’t touch upon their capabilities but whichever version you decide on should be based on what you need. The free version is more than enough if you just plan to use Postman for testing and documentation purposes, but you get what you pay for with the higher versions. That’s not to say the free version isn’t capable, because more than likely, it will do what you need it to and more.
We plan to do a series of Postman How-To’s. This is meant to give an introductory, high-level overview of Postman and some basics for getting started with your first Workspace and Collection, as well as adding documentation to your Collection. If you are not sure what any of that is yet, no need to worry. We will cover that soon enough.
How Does it Work?
Okay, now you’ve got the most basic overview of Postman and are ready to start using it. You’ve just built an API and want to test it or you’re pulling data from a third party, or you want to add documentation to a collection of APIs you or your business may have.
Whatever the reason, we’ll walk you through it. First, you will want to download Postman. You can download the free version from their website: https://www.postman.com/downloads/
Next, you should create an account, even though this is an optional step. Creating an account will allow you to save, publish, and share your collections. Once you’ve installed Postman and created your account, open Postman, and sign in. You’ll start on the Home page, then navigate to the Workspace button.
Your Workspace
From here you can create a Workspace. This is where your APIs can be stored, evaluated, created, and similar APIs can be placed in Collections. You can create your Workspace and call it anything you want. Below, you can see that we have already created a Workspace for ourselves called My Workspace.
Once you access your created workspace, you will be taken to the Workspace page. A generic workspace tab may be open when you access the workspace, but you’ll want to focus on the left-hand side. You should see the categories for Collections, APIs, Environments, Mock Servers, Monitors, Flows, and History (shown below).
For the sake of this demo, we’ll be using Collections rather than the APIs category. This is because collections are more robust. Collections also allow for API requests to be organized in a folder. APIs that are organized in a folder should be like one another, but they do not have to be.
Collections can also be shared between team members. This way, all the APIs you may be working on inside the collection will also be accessible to other team members. If a collection has previously been created and shared with you or provided to you, you can import this collection. The other alternative is to create a new collection from scratch, by clicking New.
Below, we already have two collections that we have been working with. We will be using the Survey Endpoints collection for this demo.
This is a collection of endpoints from Qualtrics that we have been using to test a few of their endpoints that retrieve survey responses.
Please Note:
Since this collection is actively being used to test the retrieval of responses for an active client project, we will be redacting any information about the client. Don’t worry though, this will not impact the demonstration.
Expanding the Survey Endpoints collection, take notice of the related endpoints inside the collection, as well as the collection description on the right side of Postman. We have highlighted both for your convenience.
We have briefly touched on collections being a group of similar API endpoints. API endpoints can further be grouped into Folders inside a collection. Your group endpoints are up to you, but we suggest grouping with similar operations. For example, if you were to place these endpoints into folders, you would place Get Survey Data, Get Survey, and Get Survey List into a folder inside Survey Endpoints because these three endpoints all deal with the retrieval of surveys and any associated survey data. You would then create a separate folder for the endpoints Start Response Export, Get Response Export Progress, and Get Response Export File because these endpoints deal with exporting survey responses.
You can further group endpoints that have been placed inside folders into subfolders. For example, you could group all GET responses into a subfolder and all POST responses into their subfolder inside the parent folder containing the survey response exports.
However, grouping API endpoints into folders inside a collection is entirely arbitrary and up to you. You do not have to place endpoints into folders. It just makes managing larger collections easier.
Postman API Documentation
Next, let’s look at the Postman Documentation section highlighted on the right-hand side.
This shows the description of the current collection. Following the steps in the image below:
The Collection Description can be edited by first clicking the Menu (1), then clicking Edit (2), and finally selecting the Document button on the right side (3).
After adding documentation to your collection, you can view it in the Postman App:
Here is where we have redacted some sensitive information, such as the client’s endpoint and API-Token but you can see that the collection description is visible (highlighted in red).
What makes Postman our favorite app for all things API endpoint related, is that it provides the ability to publish the collection to the web. Just know that once a group is published, the endpoints and their associated descriptions, and any documentation you may have written for the collection become available on the web. We have gone ahead and published this collection.
Again, we have redacted any sensitive information, but you can at least get the gist of what a published collection looks like. You can see that the collection description is visible, along with the entire collection located on the left side. The published collection shows descriptions for each endpoint, and the responses for each endpoint on the right side. It also allows anyone who accesses it to download the collection and import it into their instance of Postman.
The wonderful thing about publishing collections is that instead of distributing any documentation files you may have to anyone who needs it, you can provide the Postman documentation link to those who may need to view the documentation.
Conclusion
The ability to access all the documentation for a single Postman collection, download and import that collection, and begin editing, testing, creating, and collaborating makes Postman an incredible tool for any developer to have in their tool belt. Remember, this is all included in the free version! Incredible, right? We have not even touched on Postman’s other capabilities, like scoping variables to a collection, setting up mock servers, running the collection (and subsequently being able to set the number of iterations the collection will run for), and countless other capabilities Postman allows.
For us, Postman is such a game-changing application for software developers that every developer should at least be familiar with the basics of using Postman. Why waste time trying to document your API endpoints in one place, developing and testing in separate places, distributing the endpoints separately, etc., when you could just do all of that in one Place?
Do you need help with API management? Check out our API blog, written by our certified experts! We also provide API consulting services, as well as, API implementation services – talk to us today!