Postman Tutorial For Technical Writers

What is postman

Postman can be used for a lot of things these days but at its core, it's an API client which is a term used to describe a tool used to interact and test APIs.

why should you learn to use it as a technical writer?

One of the ways to test out APIs is to write code, however as a technical writer this is not always convenient so having access to an API client like Postman makes working and testing APIs a lot easier. Also as a technical writer, your API documentation should be as accurate as possible if not 100% accurate. The only way to ensure such accuracy is to test out what you are documenting yourself. If your development team is already using Postman, you get the added benefit of being notified when an API changes, then you can change the documentation accordingly.

Setting up Postman

Postman used to be available as a chrome extension, these days you can download the desktop version. There is also a web version so if you like you can get started without installing anything.

To get started with the desktop version head over to their download page [↗] and get the right install for your operating system. As part of the setup process, you will need to create an account, this way you can access your request history and access any team environment you have been added to. Most of what Postman provides is free of charge except for a few enterprise features.

How to make an API Request

So as previously pointed out the core functionality of Postman is making API requests, so in this section, we are going to look at how to make a GET request using Postman. We are going to be making a GET request to https://jsonplaceholder.typicode.com/todos/1. To do that we need to type or paste in the URL into the Postman URL bar, then make sure we select the right HTTP verb, in this case, GET then hit the Send button. Once the request is complete you should see a JSON response at the bottom.

A GET request is one of the simplest requests you can make, in fact, you can perform a GET request without Postman just by typing the URL into your browser's URL bar. However, to perform a POST, UPDATE or PUT request sometimes you need to send some data to the server, this is a bit more challenging to do with the browser, and that's when a tool like Postman shines. In this case, there is the Body section for that, also if you need to pass specific header values you can do that as well using the header section.

The key thing is to identify all the parts your need to make a request and to provide them in the right fields in Postman.

Creating and working with postman collection

A collection in Postman is used to refer to grouping APIs. If you happen to work on different projects at a time, you can group them so all related APIs stay under one umbrella, this way you don't go around searching for APIs when you are working. Also Postman has this concept of environment variables which makes it extremely easy to pass values from one API request to the next. Creating a Postman collection is a 3 step process

Create a new collection: Click the plus (+) button as highlighted in the above illustration to create a new collection.
Name your collection : You then get a text box where you need to provide a name for your collection. This can be the name of your project for example
Add requests to your collection: Once you have a collection you can now start adding requests to it. You also have the option of importing your requests which we will touch in the next two section.

The illustration above points to the location of all three action items.

Using variables and environments

One of the beauties of Postman is the ability to have different environments and to create environment variables. In modern API development, most software teams create multiple working copies of the API known as environments. These copies serve different purposes, for example, a staging or testing environment is used for testing out the APIs before they are shipped to be used by the end-user.

As such as a technical writer you will most likely be working with the staging environment and occasionally the production environment and a few things will be different between them. eg: the URL. Postman helps you to convert all the changing parts to environment variables, whiles the common parts stay the same across environments. This way you can quickly switch environments without making too many changes every time.

So let's say the URL for your production API is api.company.com however the one for your test environment is testing.company.com and we will like to create two separate environments to capture this, one for production and another for testing.

We can follow a 4 step process to achieve this:

Click on the eye icon to the far right of the Postman window to access existing variables and to create a new one.
Click on the add button to the side of the "Environment" label to add an environment variable, there is also the global option which will create variables that are accessible across all collections.
You should get back a text box window where you need to provide a name for your environment, in our case, this is "Test Environment"
Also there is a table-like structure below where you can now add variables and set their initial value. In our case our variable name is url and its initial value will be set to testing.company.com. You will also see the current values text field, the difference being that when you share your collection with others your current value is never shared with them, just your initial values.

You can repeat the above steps to create your production environment. Whenever you need to provide a value anywhere in your request you can now reference the variable name by putting it between double opened and closed curly brackets ie: {{url}}.

For example, by typing {{url}} into the Postman URL bar we reference the initial value we set. You can also use variables in your header, body, anywhere you can provide a value in Postman. Remember that the values will change depending on the environment you select eg: Testing environment or Production environment have different url values.

Creating and hosting your documentation with postman

One of the nice things Postman provides is the ability for you to publish your collection publicly in a documentation format. This is useful for product teams who have limited resources and will like to focus on their product as much as possible but do not want to lack in the documentation department. You can publish your collection as documentation following these steps:

View the list of collections by clicking on the collection icon to the far right of the Postman window
Hover over the collection you will like to publish and click on the 3 dots that show up next to it.
Select view documentation, this should give you a preview of what your documentation will look like.
If you are ok with the outlook you can go ahead and click on publish which should be located on the far right of the Postman window.
You should get a list of options to add some branding to your documentation and once you hit publish it's done!

Generating code samples

Whenever you make a successful API request Postman provides code samples to make the same request in different programming languages. You can copy and use or even provide this code sample to end-users of your documentation.

To view the generated code sample, first select or make a request, then click on the code icon to the far right of the Postman window. This will expose a dropdown window from which you can select the programming language you want to see the code for.

Final Words

Tools like Postman have grown to become a necessity for anyone working daily with APIs and this includes technical writers, so spending the time to learn how to use it will go a long way.

Here is another article you might like 😊 What you need to know about APIs as a technical writer

Tech Jobs | Newsletter [↗] 🗯️ Got a question? 🔗 Share on 𝕏

EDDYMENS