Postman essentials: exploring the collection format

If you’re one of the 20 million people who use Postman, then you’ve worked with Postman Collections in one way or another. Collections are a great way to organize API requests, and they allow developers to easily create, share, and collaborate on different APIs. Collections can be used for almost any API workflow, whether it’s mocking, monitoring, testing, or documenting an API. But how are collections able to do so much? Let’s take a closer look at what collections really are—starting with an overview of the collection format itself.

Related: Postman Collection best practices

What is the collection format?

The collection format is an open source JSON format that lets us organize API requests and work seamlessly across the API lifecycle. Collections provide machine- and human-readable representations of APIs that are portable, shareable, and executable. You can also define different parameters and aspects of your API. This is similar to what you can do with other API definition formats, such as OpenAPI and RAML, except that the collection format lets you create workflows for your APIs and work across its lifecycle. It can be helpful to think of a collection as an API engine—one that helps you drive an API across its entire lifecycle.

Most of the time, we don’t need to think about how collections work unless we need to do a low-level task. For instance, if you’ve ever exported a collection from within Postman, you will notice that the exported JSON file contains all the information about your collection. Importing this file back into Postman helps you pick up where you left off with your requests, documentation, environments, variables, mocks, HTTP request headers, tests, and pre-request scripts.

The collection structure is shown below:

A very basic collection in JSON will look like this:

{
  "information": {
    "name": "My Collection",
    "description": "This is a demo collection.",
    "schema": "https://schema.postman.com/collection/json/v2.1.0/draft-07/collection.json"
   },
  "item": []
}

At the top level, collections have two main properties: “information” and “item.” The “information” property contains the general metadata about the collection, such as its name, description, and schema. An “item” is the basic building block of a collection. It allows you to specify a request, its corresponding response, and related metadata. An item can be an object or an array of different items. When it is an array, it contains some additional metadata and is called an “item-group.” You can think of an “item-group” as a folder of items that optionally has its own name, description, and events.

{
  "id": "an-item-example",
  "name": "First Folder",
  "description": "This is an ItemGroup(folder) that contains two items",
  "item": [
    {
      "id": "1",
      "name": "Item A",
      "request": "https://postman-echo.com/get"
    },
    {
      "id": "2",
      "name": "Item B",
      "request": "https://postman-echo.com/headers"
    }
  ]
}

In the snippet above, the “request” property of the item has a URL as its value. However, the value of an item’s “request” property is much more than just a URL; it is an object that can be used to represent other parts of an API request, such as the request headers, body, and anything else that is needed to successfully make an API request. The snippet below shows the basic structure of a request:

{
  "description": "This is a sample POST request",
  "url": "https://postman-echo.com/post",
  "method": "POST",
  "header": [
    {
      "key": "Content-Type",
      "value": "Application/JSON"
    },
    {
      "key": "host",
      "value": "postman-echo.com"
    }
  ],
  "body": {
    "mode": "urlencoded",
    "urlencoded": [
      {
        "key": "some-variable",
        "value": "Something awesome!"
      }
    ]
  }
}

We’ve covered a basic example of what a request looks like in JSON, but there’s a lot more that can be represented with collections, such as API responses, tests, and documentation.

Why are collections useful?

Collections have a lot of use cases that vary depending on the environment in which they are run and the needs of the person running them. Here are some of the reasons why Postman Collections have become essential to so many developers:

Collections are API contracts

An API contract is a formal business agreement between producers and consumers of an API. It is a shared understanding of what an API is expected to provide. Collections are the foundation of every API contract in Postman, as their simplicity, readability, and ease-of-use makes them well-suited to serve this purpose.

Collections are API lifecycle-friendly

If you’ve ever used the API-first approach, you will understand that the ability to easily work across the lifecycle of an API is very crucial to the quality of the APIs you build. Collections give you this ability and provide a unique interface for you to easily represent different stages of your API.

Collections are highly portable

Collections have an intuitive structure and an extremely portable format that can be shared and used in different environments without losing functionality. Part of the reason collections are so portable is that everything in a collection is divided into subunits that can be reused elsewhere in the collection.

Collections work across different specs

With the help of tooling, collections are very interoperable. You can convert a collection to an OpenAPI definition and vice versa. In Postman’s API Builder, you can import your API definitions in a variety of formats, such as OpenAPI and GraphQL, and use them to generate collections for different purposes, including mocking, documentation, and testing.

How can you run collections?

The interoperability and portability of collections, which we discussed above, allows them to be run in any environment with a variety of tools. For instance, collections can be run:

On the command line, using Newman or the Postman CLI

Newman is a command-line interface (CLI) tool that allows you to run collections in a command-line environment. You can use it to run tests and integrate it with your CI/CD pipelines. Newman can also be run as a JavaScript library.

Alternatively, you can use the Postman CLI, which enables you to run your collections, perform governance and security checks, and easily test your APIs from the command line. It syncs with your Postman account and uploads your run reports back to Postman, allowing you to do all your automation testing and pipeline runs in one place.

In your code, using the Postman Runtime

The Postman Runtime is an open source NodeJS library used internally at Postman that allows developers to work seamlessly with collections. It is much more low level than Newman; in fact, Newman was built on top of it. The Postman Runtime allows you to run collections while giving you the ability to specify parameters for timeout, strict SSL, host lookups, agents, proxies, certificate lists, and more. The Postman Runtime is also used by the Collection Runner in Postman to run your collections.

With the Postman API and webhooks

You can use the Postman API to create a webhook that lets you initiate a collection run by sending a request to it. This is particularly useful if you have some automations running and you want to trigger a collection run in response to a specific event.

Collections can do much more than most people think; there is so much that can be built and achieved with the format. The schema is completely open source and can be found on GitHub.

Technical review by Arlemi Turpault and Melinda Gutermuth.