5 Feb 2021

Pagination with Postman

When the list of returned items can get quite big, our API endpoints provide pagination to retrieve the items in batches.
You can limit the number of items that are returned in a single request using the limit URL query parameter.
If more items are available then the response will contain a next property that provides the URL you need to call to get the next number of items.
That URL will include the startAt property as well that you need if you want to generate the URL yourself or through one of our SDKs.  

In case of using code (Node.js, .NET, etc) you can just write a recursive function that keeps calling the same endpoint as long as the response contains a next parameter.
How could you do the same in Postman?

That program provides many useful things that will be needed: Pre-request Scripts, Tests and Environment variables.
We already have an article that is taking advantage of these: Automation Test & Automate workflow with Postman Collection Runner

Let's start by creating a request like this:


Get buckets

As always, you also need to provide an access token in the "Authorization" request header. In my case it's stored in an environment variable called AccessToken.

Authorization request header

In order to access the first batch of items, we should not provide startAt, since we cannot guess what its value should be.
Also, if no limit has been provided as an environment variable, then let's ignore that too. Just add this on the "Pre-request Script" tab:

if (!pm.environment.get("startAt")) {

if (!pm.environment.get("limit")) {

Once the request returned, we can check if the reply contained a next parameter. If it did, then we can store the startAt value from it. Add this on the "Tests" tab:

// This will produce a nice message after the run in the "Test Results" tab 
tests["Got buckets"] = responseCode.code == 200;

let jsonData = JSON.parse(responseBody);
if (jsonData.next) {
    console.log("More items available");
    var sdk = require('postman-collection');
    let url = new sdk.Url(jsonData.next);
    let query = url.query;
    postman.setEnvironmentVariable("startAt", query.get("startAt"));
} else {
    console.log("No more items available");
    postman.setEnvironmentVariable("startAt", null);

You can add nice messages to the "Test Results" tab by adding a property to the tests object and assign true or false values to them (as shown above), meaning pass or fail respectively.

Test results

Now we can just keep sending the same message and it will return more and more items until all have been returned. Then it starts again.

In case of the Forge app I tested with, this is what I'd get as I keep calling the same endpoint:



Related Article