Introduction to Postman
A short guide to getting started with the popular API platform.
Interested in the API-building tool Postman, but not sure where to start? This “from-scratch” introduction leverages Postman itself and some clever work by others to learn the fundamentals. It doesn’t cover creating new collections or environments, but it does explain how to use existing collections and backend systems shared by an organization.
What is Postman
When we think about websites and mobile apps, we typically think about the user interface, the part of those systems we interact with.
The brains of these systems are usually on remote systems and our devices communicate with them in ways that are hard to perceive. Even when developing or testing applications, these backend systems can be abstract. They’re critical to the function of those applications and the businesses founded on them.
Postman is a tool that makes these abstract backend systems more concrete and allows testing, documenting, and collaborating with them easier. Some features that make Postman powerful are:
- Native or web – access Postman with a native application or through a browser
- Collections – backend requests organized into groups and sub-groups
- Environments – duplicate copies of backends with subtle differences, like development, staging, and production
- Workspaces – grouping of collections, environments, and APIs into an organized, sharable unit
- Documentation – having good documentation living within the context of Postman’s tools makes for a wonderful experience especially when developing or troubleshooting unfamiliar or difficult systems
- Debugging – clean interface to see responses and identify what isn’t working correctly
- Testing – writing code within Postman to automate repetitive tests
- Collaboration – comments and updates of workspace elements from an organization
Getting Started
Create an Account
Your work in Postman is tied to an account on their backend services which allows you to work from multiple systems with ease. Go to Postman’s account setup page and follow the steps there to create an account if you don’t have one.
Install the Client Application
You can use Postman from a web browser, but there are limitations to this and you may need to install a helper app, anyway. We recommend installing the native Postman application which doesn’t require any additional setup.
Visit the Postman downloads page to download the Postman App. Select the correct download for your operating system and hardware. Open the downloaded file and follow the instructions to install the app.
Launch the app and you’ll be ready to go.
Getting Your Bearings
Postman does a lot of different things, so the interface is somewhere between these two options:
(Maybe it’s reassuring that there are always more complex systems?)
By default when opening Postman, you’ll be in the Home tab. This page has links to useful resources, your recent work in the middle, and an activity feed on the right with changes made to workspaces that you follow. Along the top are several other tabs (Workspaces, API Network, Reports, and Explore) and a search bar. You’ll spend most of your Postman time in the Workspaces tab working with a single workspace.
You should have a starting workspace called `My Workspace` that was created automatically when you created your account. Click on `Workspaces` in the tab bar and in the pulldown, look for `My Workspace` and click it. If you haven’t added any collections to your workspace, it will look a little empty, but we’ll fix that soon.
The `A` region in the screenshot organizes the different things that make up a workspace: Collections, APIs, Environments, etc. The `B` region will show a list of whatever element is selected in `A.` In this screenshot, there are no collections added to this workspace, so it’s showing an empty state.
Once you select something in the `B` region, the details of that will show up in `C`, the region in which you’ll spend most of your time using Postman. This area can vary significantly depending on what you’re doing and we’ll see a few examples soon.
Follow the First Tutorial
We’ll start with a tutorial from Postman. It’s a great 10-minute introduction that gets you familiar with the interface and high-level concepts.
There are many other resources for digging deeper into various Postman topics, so once you get the basics you can find similar learning collections suited to your specific needs.
Let’s start by forking the tutorial collection.
Forking a Collection
Once you’re logged into Postman, use the search bar at the top of the interface and type “learn-by-api” and look for the highlighted result in the screenshot below.
After you select this collection, you’ll see the view below. At this point, you can’t interact with the requests in the collection as they aren’t yours to change. To do this, you need to make a copy in your workspace, a process called creating a fork. There are at least four ways on this screen to create a fork, which is a nice way to make a complex tool. One of these will make the most sense to you.
Three of these approaches are highlighted below with arrows, the blue arrows requiring two clicks. Pick one and click.
Whichever way you choose to fork the collection, you’ll get to the same place:
Here you need to give the collection a name (calling it the same thing `learn-by-api` is fine). Then click in the Location field and select `My Workspace`. The `Watch original collection` checkbox lets you choose if you want updates on your home tab when there are changes to this collection. You can safely turn this off, but for collections you’re working on, this is a good setting to leave on.
Click `Fork Collection` to create your forked copy of the collection. You’ll see a similar screen with a little more information.
Show the Documentation
In tutorials and in real work, viewing documentation can make a complex task simpler. Within a collection, you can show the documentation pane by clicking on this icon near the top right corner of your screen:
The documentation pane will slide in from the right side. You can mouse over the other icons here to see what else is available, things like comments made by teammates, changes made to the collection, etc.
Not all collections have added documentation, but good tutorials usually will and will offer instructions on how to use them. Likewise, good backends have documentation and this is a nice place for it to live.
Follow the Documentation
This tutorial starts with the documentation. Follow the steps outlined in a red box in the screenshot below.
When you follow these steps, you’ll see the main interface change. You’ll click the collection name in your workspace pane which will open a sub-item. When you click it, the documentation pane will dismiss (which is fine, you can leave it closed). Click the Send button, which sends a request. The response will display in the bottom of the center pane of the window.
It doesn’t mention doing this, but if you click the `Visualize` button just above the response section, it will render the output the way it is shown in the documentation above and will be easier to read. The response is providing the next step of the tutorial. Follow that on to the next step and on to the end of the tutorial. After you hit `Send` and click `Visualize` your screen should look similar to this:
Next Steps
The introductory tutorial collection was just the beginning. There are other collections that you can fork to explore more of Postman in greater detail. Search for `learn` in the search bar, for example, for some possibilities.
LearnPostMan Workspace
In Postman, use the search bar at the top of the window to search for `learnpostman` and select the workspace by Mukesh Agrawal. This is a large workspace with about 50 collections neatly organized by day.
The idea of a 30-day study course is nice, although many of these topics will take only a few minutes to work through.
It’s not possible to fork an entire workspace, so you’ll need to for individual collections within this workspace one at a time. If you mouse over one of these collections as shown in the screenshot above, a three-dot menu will appear to its right. Clicking on this context menu will give you the option to fork the collection. You can fork this into your default `My Workspace` or you can create a new workspace to hold these collections.
Not every role (QA, developer, producer) needs to work through all of the tutorials. As you work through them, you’ll get an idea of what is appropriate for you given your anticipated use cases for Postman. At a minimum, we recommend:
- Pre-requisites – Day 00
- Fork a collection – Day 01
- Collections and environments – Day 02
- Add request details – Day 03
- Authorization – Day 04
- Variables – Day 05
- Debugging – Day 07
- Run a collection – Day 08
These collections will give you a solid overview of the system. If you know you’ll be using a GraphQL backend, for example, fork day 19. If the system you’ll be working on uses OAuth, day 14 is there waiting to be forked.
Additional Collections
Looking for something not covered in the previous collections? The best bet is to search in Postman, then search Google, and then ask around. It’s possible that someone familiar with your project will have suggestions for collections to explore or for keywords to search to find just what you’re looking for.
Additional Resources
Postman has an extensive documentation library on their site with text and video resources, covering a variety of use cases for different roles.
Webinars
This webinar series provides nice instruction for specific roles:
Small Planet
Small Planet creates award-winning mobile and web products. We provide full UX design, development, QA, team support, and product management services. Follow us @smallplanetapps.
