Hyperswitch | Here's a better storage format for postman collections

Home > Blog >

Here's a better storage format for postman collections

Natarajan Kannan

Published on: Nov 16 2023

At Hyperswitch, we are building an open source payment orchestration solution and the last thing we want to spend time on is trying to identify postman collection diffs manually while reviewing pull requests. The root cause of this challenge is the current collection format. We've come up with a new file format for maintaining postman collections. Let's jump right in!

Postman collections are created using the Postman UI application. These collections are represented as a JSON file by the Postman UI application. It is a single file that contains all the requests/tests/variables etc of the collection. It is designed to be edited within the Postman UI. The newman tool allows teams to run Postman collections as part of their CI pipelines by supplying the Postman collection file as an argument. Typically, teams that rely on Postman for their API testing in CI pipelines maintain a copy of the collection file in their source repository. When teams maintain the Postman collection in their repository, they will have the following workflow to make changes to it and push it upstream:

Import the collection json file from the repo into Postman UI
Make changes to the collection in Postman UI
Export the collection to a file using Postman UI
Commit and push the changes

There are a few challenges with the above workflow:

1. Collection file diffs are very hard to review in pull requests

https://github.com/juspay/hyperswitch/commit/7e29adb5c9dee8b03ef58ccbd85b07b106459380

New format collection diff: https://github.com/juspay/hyperswitch/pull/2117/files

2. Developers cannot use their favourite editor to make changes, add/remove new tests.

As a consequence of the above, collection maintenance suffers and often become stale.

Solution to the above challenges

The core reason for challenges presented above is the file format in which the Postman requests are maintained. A single JSON file that encapsulates the entire request code and sequencing does not lend itself for easy reviewing and be an all-editor friendly format.

This fork of newman attempts to address the challenge by representing the Postman collection as a set of directories/files. It allows developers to create Postman collection using the directory representation and also run them. It achieves this by re-constructing the collection json from the directory/file structure and leveraging the existing newman run implementation.

For example, this is the directory equivalent representation of a sample collection in the examples directory as generated by the dir-export command.

Directory representation of collection

The following is a tree structure of the directory that represents the Postman collection with annotations of what each file corresponds to in a Postman collection.

Next steps

This concept of representing Postman collections as a directory opens up programmatic pre-processing of request data before running the requests. This could include things like the following:

Re-using same data across requests
Using other javascript libraries in testing code

The instructions for using the tool are given below. Please give it spin and let me know it you if it is useful.

Usage

Installing newman from this fork

One can install the newman executable in this fork using the command:

npm install -g 'git+ssh://git@github.com:knutties/newman.git#feature/newman-dir'

The following no-arg run shows the new commands added to newman to help manage Postman requests maintained as directories/files instead of a single json file.

The following sections show the invocation of the different commands added in this fork of newman.

Create a new directory based Postman collection

newman dir-collection-create new-dir-collection

Generating directory representation for an existing collection

newman dir-export examples/sample-collection.json

Convert a directory representation back to a Postman collection json file

newman dir-import examples/Sample\ Postman\ Collection/ -o examples/sample-collection.json

Diff the collection generated by export followed by its import

This command is typically used to test the tool itself to ensure it can handle all collection json use-cases.

newman dir-export-import-check examples/sample-collection.json

Execute a Postman collection stored in the directory format

newman dir-run examples/Sample\ Postman\ Collection

The dir-run command supports all the options that the stock run command of newman supports. This is achieved by re-using the same set of command options for both the commands.

Sample output of dir-run shown below

Add a folder under a existing directory

newman dir-add-folder examples/Sample\ Postman\ Collection/folder1

Add a request under a directory

newman dir-add-request examples/Sample\ Postman\ Collection/test4

This command adds the request to the end of the requests already present in the folder. The order of the requests is stored in a separate file called .meta.json. The order of requests can be changed by re-ordering the requests in this file.