Postman is among the most essential tools for web development. Whether for PHP, Node.js, Ruby on Rails or Python development, if you interact with an API, Postman is the reference tool you will be using.
Get started with Postman
Postman is used to execute HTTP calls directly from a GUI. You can simply choose the URL, the HTTP method (usually GET, POST, PUT, PATCH and DELETE), the headers , the query params and in some cases the body of the request.
How does Postman work?
HTTP requests
This is the most trivial functionality to which this tool responds, being able to simply make HTTP requests. The graphical interface makes the exercise as easy as surfing the internet on a modern browser. Just fill in the URL and the HTTP method.
The HTTP methods differ depending on the desired operation and the API on which you are doing your operation. Here are the most used HTTP methods and their functions:
- GET: GET requests are those made by a browser when you enter a URL in the navigation bar. Their purpose is to fetch a page or data.
- POST: POST requests are intended to send information, contained in the body of the request, to the server.
- PUT : PUT requests will overwrite a resource with new data, again present in the body of the request. It is used to update data provided that one is able to provide the updated resource in its entirety.
- PATCH : PATCH requests are also used to update a resource but only modify the element sent in the body of the request.
- DELETE : as its name suggests, the DELETE request is used to delete a resource
These uses of HTTP requests vary by server and how it was developed, but these methods are the most common for REST APIs.
HTTP requests sometimes include query params. This is the data sent to the server via the URL, most often in GET requests, passing this data in the format key=value followed by a ?.
leboncoin.com/search/?category=9&locations=r_12
fields category and location are query params .
Related: Mongodb beginners guide.
Postman makes it easy to define and modify these query params directly in its interface.
HTTP requests can also include Request headers. These are data transmitted in the header of each request with different uses. In some cases, you need to specify certain headers, such as an authorization or authentication token.
Postman allows you to modify headers with the same simplicity as for query params via its graphical interface.
Some HTTP requests are of interest only because they send data to the server via the request body of the request. This is the case for POST, PUT and PATCH requests. The body data to be sent to the server via Postman can be of different formats but the most used is the JSON format, followed by the XML format for SOAP APIs.
Postman allows you to copy and paste a body into a text box and choose the correct format.
Some HTTP calls require caller authentication. tab Authorization, you can set the necessary authorizations for your calls. Postman offers various forms of authentication, such as simple API key, Basic Auth or OAuth.
The collections
Throughout your development, your API grows and the URLs to test via Postman become more and more numerous. To help you organize and store queries for later replay, Postman suggests using collections.
This is a directory where you can save and file a series of HTTP requests.
How to order these calls in your collection is completely up to you. Postman also allows you to automatically execute all the calls of a collection one after the other, hence the importance of defining the order.
Use variables
As soon as you start developing your app, you’re going to have some calls that depend on variables from other queries. For example, you will probably need to retrieve an id or token from a first call in order to be able to make the second.
To avoid having to copy/paste each time you want to launch your calls, you have Postman variables. They will allow you to store data received from a request to be able to reuse it in other calls that follow.
Scope of variables
Postman variables are stored in different scopes. The main scopes are:
- Global Variable
- Environment variable
- Collection variable
- Variable Locale
- Data
The advantage of variable scopes is to be able to use them in different collections, to create environments having specific variables, such as a production URL different from a pre-production or development one, and to be able to share them via a mechanism export and import of JSON file.
Define variables
In order to define a variable, Postman offers the pm containing the functions set and get. Depending on the scope of the variable you want to set or retrieve, you will use:
pm.global.set(name_of_variable,'value')for a global variable, or
pm.environment.set(name_of_variable,'value')To retrieve the value of the variable in your URL or in your body, you can simply include its name between double braces like this:
https://{{url}}/ressource/{{currentId}}Pre-query or Post-query
In your use of Postman, there are 2 key moments where you will be able to define variables and, more generally, execute code. Before the HTTP request is sent to the server or after.
Defining a variable before the request is done in the Pre-request Script of the Postman interface. You can use this variable in the url, header or body of the request.
If, on the other hand, you need to retrieve data from the response of a previous HTTP call tab Tests in the previous request to define the variable.
For example:
You want to use a secure API to delete items older than three days. Your HTTP call sequence goes like this:
- POST call to the URL /login with your username and password, this returns your JsonWebToken to make calls to the following routes which are secure.
- GET call with the JWT in the API-KEY header on the /items route with in query filter today’s date minus 3 days
- DELETE call with the JWT in the header on the /items/:id route for each item to be deleted
In this case, you will need to use both the Pre-request Script tab Tests to define your variables and use them as Query Params, Headers and URL.
Accelerate your development with Postman
Postman exists to help us developers work faster and more efficiently. As soon as your application passes a certain critical size, Postman will also grow and be much more than a tool for simply making HTTP requests in a nice graphical interface.
Write automated tests
In any API development process, unit and functional tests are essential to ensure its proper functioning and its non-regression when developers code on it.
Postman also offers a testing function. The advantage of tests via Postman in addition to functional tests, also called integration tests, which are included in your codebase, is that the latter should “mock” any call to an external API.
Indeed, when you develop your Backend, your tests must cover your logic. If you’re calling the Twitter API, you won’t actually be making calls to that service every time you do integration testing, you’ll be mocking those calls.
If for some reason the Twitter API is unavailable, you don’t want to break your continuous integration pipeline and work on a bug fix that is beyond your control. This is why you must “mock” calls to external APIs in your automated tests.
On the other hand, you could have a test suite in Postman that actually calls all the external services. This layer would come in addition to the integration tests and could be launched regularly to ensure that even by connecting the real services, everything is still going well.
Test the returns of an HTTP call
Postman uses Chai to evaluate the return of the HTTP request with the test code you wrote. When you run your request, Postman sends you the response and runs the tests.
You will be able to evaluate the contents of the http response using syntax Expect of Chai.js. Postman offers out-of-the-box test snippets that pop into your query’s Tests tab with a click. Although they are handy to start with, I advise you to refactor your test code whenever there is more than one. Indeed, the code snippets offered by Postman are independent and will duplicate a lot of code.
For example, using Postman to test that the server response contains specific variables via postman snippets, your code would look like this:
pm.test("Response contains foo", function () {
var jsonData = pm.response.json();
pm.expect(jsonData.a).to.eql("foo");
});
pm.test("Response contains bar", function () {
var jsonData = pm.response.json();
pm.expect(jsonData.b).to.eql("bar");
});However, in this case, the jsonData variable is unnecessarily duplicated. You might have a single block of code like the following:
const jsonData = pm.response.json();
pm.test("Response contains foo and bar", function () {
pm.expect(jsonData.fizz).to.eql("foo");
pm.expect(jsonData.fizz).to.eql("bar");
});This block of code is easier to maintain than the first one. Especially since you won’t have the help of a Git Hook to ensure that your tests cover your code well, so you will have to be contented with your developer skills in order to maintain your tests.
Test a collection
All the interest of Postman comes in its automation. Postman lets you run a series of HTTP requests one after another by saving them to a collection and then executing that collection.
Thanks to the use of variables, you can create a sequence of requests which will take the data from the responses for the following requests. Each request will be examined by the tests it contains and at the end of the process Postman returns a report of all the successes and failures of the tests.
Workflow of HTTP calls in a collection
When you design a collection, you are free to define the order of the calls. By default, Postman will launch calls in the order the calls were recorded.
In some cases, you might want to control the order of queries based on the result of a previous query. For this, Postman offers you the possibility to control your workflow via the method setNextRequest().
In the Tests tab, you will be able to use this function using JavaScript code to determine the conditions and the query to call accordingly.
Integrate Postman into a CI/CD pipeline
Newman: Command line postman
Newman is a CLI tool that allows you to launch a collection in a terminal. This feature is very useful when you want to integrate Postman tests into a continuous integration pipeline.
Postman Monitor: Monitor the performance of your API
Offered in the paid version of Postman but available to a certain limit to all users, Postman Monitor is a service that allows you to run tests periodically on your API.
The API tab offered from version 7.1 of Postman will serve as the central point of your API, grouping the collections, the tests and potentially the mock server. This tab is used to centralize all resources related to your API such as environments and documentation. By defining the schema of each resource, for example above the users , Postman will be able to automatically generate the collections.
Mock a server to do its development
Postman’s Mock Servers will also enable you to simulate your API by recording responses from a real API and outputting them when you call this mock server.
This feature is particularly useful for Frontend developers who do not yet have access to a functional backend (this one may also be under development) or when you want to use third-party APIs that charge or limit depending on the number of calls made.
For example, I experimented with the Google Maps API which charges $17 for 1000 calls. Being in development, I don’t want to be charged for the calls I can make as tests. In these cases, I can create a mock server that will return the answer(s) I want as if they came from Google Maps.