New documentation for the collection format

Gbadebo Bello

March 6, 2023

When you think about Postman Collections, the first thing that often comes to your mind isn’t a JSON-based API specification. The first thing that most likely comes to your mind is an API request or a group of API requests and how they are run and organized.

Related: Use the API Documentation Template

The collection format is the specification that drives Postman Collections, and it provides a unique way of organizing API requests and modeling API workflows. Previously, the only resource available for learning about the format was the auto-generated documentation hosted on schema.postman.com.

This documentation has a reference-based approach to explaining different units of a collection. Each unit has several deeply nested nodes that may be endlessly traversed, which does not give you the best experience possible.

We’re excited to share that learning about the collection format just got a lot easier with Postman’s new and revamped documentation. Here’s what has changed:

• New look and feel: The documentation now has a new look and feel inspired by the Postman Learning Center’s flow and structure.
• Better SEO: The new documentation is hosted on the Learning Center and has an improved SEO, which makes its resources more visible on a web search.
• A walk-through, not a reference: The new documentation walks you through the different units of a collection and how to author your own collection definition, starting from the most basic form of an API.
• Comparison with collections in Postman: The documentation consistently compares how a collection is represented in the spec and how it is represented in Postman; it has an entire section highlighting these differences.
• Multiple references: A reference section includes an image, table, and schema reference of different units of a collection.

Documentation sections at a glance

For easing viewing, the documentation has been divided into the following sections:

Getting Started

The Getting Started section introduces you to the most basic form of a collection and how it can be used to model very simple APIs. This section helps you quickly understand what a collection is, how it is structured on a high level, and how to model a simple API request in a collection.

Concepts

This Concepts section delves deeply into the different aspects of a collection and how to work with them. It covers every part of a request, how to save responses, working with events, variables, and more.

References

The References section has resources for the different properties of a collection unit. A reference is presented in three formats for each unit:

• Reference Tables: Tables containing the properties, description, types, etc., of each field in a collection unit.
• Reference Diagrams: Diagrammatic representations of the collection unit.
• JSON Schema: The JSON Schema definition for just that unit.

What’s next?

Collections aren’t complete without the tools built around them that help you run a collection, generate code, convert to other specifications, and do many more interesting things. There will eventually be a documentation section that will cover the different tools Postman provides for collections and how to work with them. Keep an eye on the Postman blog for more updates.