Diving-Deep: Postman’s Open-Source Collections Format (Postman 3 of 4)

Explore Postman's open-source collections for seamless API collaboration

Introduction

The Postman Collection Format is a standardized specification and format to create, use and share API environments. It was developed by Postman, the most popular API development and testing tool, but a Collection Format is an open-source, open specification in JSON format.

Postman Collection Format

Structure of a Collection

There are five keys that define a collection object

• $ info 

  • Contains metadata about the collection such as name, description, schema version, and more

• $ item

  • Represents individual requests or folders
    Each request can have various details like method (GET, POST, etc.), URL, headers, body, etc

• $ event 

  • Allows for scripting and automation of requests using pre-request and test scripts

• $ variable

  • Variables that can be used across the collection for dynamic data

• $ auth

  • Authentication details for API requests

Open Source vs. Postman Proprietary

Open Source Components

• Postman Collection Format

  • The format itself is open source and its specification is publicly (open license)

  • This means anyone can create, read, and manipulate collections outside of Postman

• Postman SDK

  • A Node library for working with Postman collections programmatically

  • It allows for creating, reading, updating, and transforming collections using JavaScript

• Newman

  • Newman is a CLI tool to run Postman collections

  • This is an open source project and widely used for CI/CD and automated testing

Proprietary Postman Components

• Postman App

  • The Postman App (Desktop, Web) is the first and main proprietary part of Postman

  • The app itself is proprietary software, though it's available for free

• Postman Pro and Enterprise

  • Paid plans that offer additional features such as enhanced collaboration, monitoring, and API documentation hosting

• Postman Cloud Services

  • Postman also offers other cloud-based services that accompany the main product 

  • Features include … cloud-based workspaces, API monitoring, and version control for collections are part of Postman's proprietary offerings

This tutorial will cover Postman Collection’s architecture, key concepts, and practical use cases to give you ideas on how to use it.

Contents

1. Architecture Overview

2. Concepts

3. Reference

---

Architecture Overview

A Collection is an API specification 

• It provides a format for representing, modeling and organizing different parts of an API request or workflow

Features 

• Share and execute API requests

• Define different aspects of your API

• Models workflows

• Work across the lifecycle of your API

• Document and test

Example Collections

The Collection Format is open source

• The basis of Collections in Postman

• Advantages

  • Human readable and machine interpretable (JSON)

  • Interoperable (OpenAPI, GraphQL)

  • Portable 

  • Code and documentation generation

Structure of a Collection

1. Info

2. Item

3. ItemGroup

4. Request

5. Events 

Consists of a set of reusable parts, known as units

• Units can be nested within each other and used in different parts

Info

• A collection has a single info block

• $ info contains metadata about the collection

  • Collection name

  • Schema

  • Version

  • Description of the collection 

Item

• The Item is the basic building block for a collection

• Represents an HTTP request, along with the associated metadata

• $ item is an object or array

• Contains 

  • An API request

  • An API response 

  • Related metadata 

ItemGroup

• A container for items (like a folder)

• Properties

  • $ id 

  • $ name

  • $ description

• A collection is an item group with an additional and special info block

Request

• Represents an HTTP request

• A request can be found within an item or item-group → item

• A request can be specified as a string or JSON object

  • If string, it is assumed to be GET request

Events 

• Events let you declare scripts (pre-scripts) to run at certain stages in the lifecycle of a request/collection

• Written in Javascript

• Run using the Postman Sandbox

Event Types

There are two types

1. Test Script

   • Associate a test script with an item

   • Executed after the actual HTTP request is sent and the response is received 

2. Pre-Request Script

   • Executed before the HTTP request is sent 

Postman Sandbox

https://github.com/postmanlabs/postman-sandbox

• A Sandbox for Postman Scripts to run in Node or the browser

• You can trigger requests and listen back for events

---

Defining an API

https://learning.postman.com/collection-format/getting-started/defining-a-simple-api

Contents

1. API Structure

2. APIs with Multiple Requests

3. Nesting Folders

API Structure

A collection has two mandatory units

• $ info

• $ item

The minimal API implementation

The request above is a URL and defaults to GET 

APIs with Multiple Requests

• To define multiple requests, item becomes an array of item objects

Nesting Folders

• Item groups (folders) can be nested inside folders

• These allow you to organize APIs based on different types of objects or blocks based on your requirements

---

---

Concepts

Contents 

1. Structure of a Request

2. Structure of a Response

3. Variables 

4. Events 

5. Documentation

6. Extending Collections

7. Differences Between the Collection Format and Postman Collections

---

Structure of a Request

• Collections let you organize API requests

• An API sits between an application and a server

• An app can use an API to communicate with a server and perform actions with the use of a database

Contents

• Request object

• Request headers

• Request methods

• Authorization

  • Auth attributes

• Description

• Request body

  • mode

  • raw

  • urlencoded

  • formdata

  • file

  • graphql

• URLs

• Configuring proxies

• Certificates

Request Object

• When a request is a string, it is a simple GET request

• If it is not a string, it is a more sophisticated request - an object

Example

• URL - The request URL

• Auth - Reference Object

  • The authentication helpers 

• Method - HTTP Method (GET | POST | PUT | PATCH | DELETE)

• Description - Raw text or an object that holds the description along with its format

• Header - An HTTP header

• Body - The data contained in the request body

• Certificate - SSL certificate

• Proxy - Configure a custom proxy in Postman for a particular URL match

Request Headers

• This can be an object or array of objects

• Each is object is represented by a KV pair object 

Properties

• Key - The key of a specified header attribute

• Value - The corresponding value

• Disable - Boolean - Indicates if the header is included or not in a request

• Description - A nickname that describes the header attribute 

Request Methods

Supported HTTP methods

$ GET | PUT | POST | PATCH | DELETE | COPY | HEAD | OPTIONS | LINK | UNLINK | PURGE | LOCK | UNLOCK | PROPFIND | VIEW

Authorization

• These help to validate the client side identity using a client-provided credential

• Data is transferred in plain text or in an encrypted form to a server

• The server then validates the authorization credentials 

You can specify these types of authorization headers in request definitions

$ apikey | awsv4 | basic | bearer | digest | edgegrid | hawk | noauth | oauth1 | oauth2 | ntlm

Authorization is represented using the auth attribute

• It requires a ‘type’ KV with any of the types above

• Next, you specify the authorization values in a basic object or array

Auth Attributes

• An auth attribute is a JSON KV object

• Represents the credentials contained in an authorization

• The authorization of type basic has a basic property

• An auth attribute refers to the basic property, with its list of objects

This is an example of a full request object

This object contains an auth object and an auth attribute of ‘bearer’

Description

• Add more context to your definitions

• They can be string | objects 

• Objects can contain Markdown, HTML or plain text

Request Body

Collections support five request body types

$ raw | urlencoded | formdata | file | graphql

Properties

• The mode is the type field

• Then, you use the type name as a key to specify the object 

• Raw

  • A string or serialized version of the request payload

  • The serialized data can be JSON | XML | HTML | plain text

• URL Encoded

  • URL-encoded data in KV pairs

  • You can also add the disabled property and a description

• Form Data

  • Similar to how URL Encoded is defined

  • Define text, files or any type of data to submit over an encoded multipart/formdata

  • If your data is a file that uses an absolute or relative path, use src instead of value

• GraphQL

  • GraphQL requests are made over HTTP in the same way as GET | POST | …

  • Collections should be provided in the request body, specifying the schema and variables

Proxies

• If you have a proxy set up, you can provide configuration for a proxy

• The proxy request helps you do this with the following properties

  • $ match - The URL match for the proxy config

  • $ host  - The server host

  • $ port - The server port

  • $ tunnel - The tunneling details for the config

  • $ disabled - Whether it is enabled or not, allowing you to define it without having it always on

Certificates 

• Specify one or more SSL certificates using the certificate property

• Each certificate has the following

  • $ name -  A name for reference

  • $ matches - An array of URL match pattern strings to identify URLs this certificate can be used for

  • $ key -  An object containing path to file containing the private key on your local file system

  • $ cert - An object containing the path to the file certificate on your local file system 

---

Structure of a Response

https://learning.postman.com/collection-format/advanced-concepts/response-definition

For every request made over HTTP(S), there is an HTTP(S) response

• There is a response object in Postman, under a collection 

• This allows you to represent and utilize response objects

Contents

• Original Request

• Headers

• Body 

Response Object

• Lets you define different parts of an HTTP response 

• Includes

  • Status

  • Response headers

  • Response body

  • Original request 

---

Variables 

https://learning.postman.com/collection-format/advanced-concepts/variables

Variables in collections let you declare a value once and reuse it later

• You can use them in multiple places 

Contents

1. Definition and Usage

2. Collection Variables

3. Unit Variables

4. Use Cases

Definition and Usage

• A variable is defined using a variable list

• A variable list is an array of variable objects

• Each variable object has a KV pair and some metadata 

An example of a variable type

To use a variable, place double (two) curly braces wherever you need them

Variables can use in the following locations

• URLs

• Request headers

• Request bodies

Example: {{variable-key}}

Variables can also be scoped on a global | collection | request level

Collection Variables

Collection variables are declared in the upper scope of the collection object

• These can be used anywhere within a collection 

An example of a Collection declaration with a variable

Unit Variables

• Collections consist of substructural parts known as units

• Units can be nested within another unit

• A variable is an example of a collection unit that can be nested in other units

• When a variable is nested in another unit, it is called a unit variable

• Unit variables are scoped to the unit in which they were declared - and don’t exist outside it 

Collections come with two unit variable scopes: item and URL

Item

• Item-scoped variables are scoped to the item unit of a collection

• Recall that an item refers to a request-response pair

• This defines the use location of a variable

In this example, you see that the variable customerData is defined inside the item scope

This is being used in the body of a request

The variable is scoped to this item and cannot be called by other items 

URL

• Variables can also be scoped to a URL

• This means that they can only be called or used from within that URL object

Use Cases

1. Variables in query params

2. Variables in a request body 

3. Variables in GraphQL

Variables in query params

Variables in a request body 

Variables in GraphQL

---

Events 

https://learning.postman.com/collection-format/advanced-concepts/events/

Events let you declare scripts that you can execute at certain stages of the lifecycle of a request or collection 

• Scripts are written in Javascript 

• Scripts can be executed using the Postman Sandbox 

Pre-request Scripts in Postman | The Exploratory

Inside a Collection > Pre-request script 

• This runs before every request in a collection

• For an individual request, you have exactly the same menu inside an individual request 

Pre-requests have access to the Postman objects and you can do any of the following, among other things

• Get an environment | collection | global variable

• Set an environment | collection | global variable

• Log messages to the console

• Run general operation / execution scripts written in Javascript 

Scripts

1. Pre-Requests - Runs before requests execute 

2. Tests - Runs after requests execute 

Contents 

1. Event Object

2. Scripts

3. Pre-Request Scripts

4. Test Scripts 

Event Object

An event object is defined using an event-list, which is an array of event objects

Scripts

• Scripts listen to events and fire when they occur

• The script object defines the code that runs

Properties

• $ id 

  • A unique, user-defined ID

  • Refers to this unique script

• $ name - The nickname / name of a script 

• $ type = text/javascript

• $ src - A reference / path for external scripts

• $ exec - An array of strings, each representing a Javascript line, in sequential order

Scripts allow you to model workflows for requests 

Pre-Request Scripts

• These listen to the prerequest event type

• Execute right before a request is made 

• These allow you to modify headers, parameters, variables and more

• These are also useful for data pre-processing and logging 

Test Scripts 

• These listen to the test event type

• Execute right after you receive a response from a request 

• You can utilize the response data, transform it and use it for other purposes 

• You can also run assertions against the response 

---

Documentation

https://learning.postman.com/collection-format/advanced-concepts/documentation

Documenting Collections

• Collections have different units that each describe a specific block

• is it is recommended that you use the description object for each of these sections to document your API

Description Object

• All descriptions, on every entity object, can be specified as plain text | Markdown | HTML or any MIME type

Entities with a description Object

• Collection

• Folder (ItemGroup)

• Request

• Response

• Variable 

• API Schema

---

Extending Collections

https://learning.postman.com/collection-format/advanced-concepts/extending-collections

Collections are multiple sub-structural parts, known as units

• Each unit defines a part of your API

• Extensions allow you to extend these parts 

  • Provide more metadata

  • Add more fields or data

• You can place them on any collection

• Designated with a prefix “_” underscore before the field names

• They can contain any data type … strings, objects, integers, etc 

---

Collection Format vs Postman Collections

https://learning.postman.com/collection-format/advanced-concepts/collection-format-vs-collection-in-postman 

When you export a Collection in Postman, you are exporting a JSON object in the open-spec format

• This is the JSON Collection format that defines your API

• It includes all of your 

  • Headers

  • Request bodies 

  • URLs

  • Variables

  • … and more 

There are some differences between Postman collections and the Collection format

• Postman provides extra functionality abstracted over the format to improve experience 

• In an export, certain Postman-specific items will not be included in the exported JSON

Contents

1. Auto-Generated Request Headers

2. Schema Referencing

3. Variables and Environments

4. Cookies 

5. Scripting 

6. protocolProfileBehavior

7. Proxies 

Auto-Generated Request Headers

• Headers is available on a collection or request

• You can include multiple headers in a single request 

• Postman assigns default headers on collections and requests

• When you export in Postman, default headers (set by Postman) are not included 

• The Postmans info icon indicates that they’re recommended headers

Variables and Environments

Variable Scrops

• Global variables

  • Available across an entire workspace

  • You can use them in any collection within that workspace

  • When you export a collection that uses a global variable in Postman, the reference to that variable is included, but the declaration of the variable isn't included in the export because it isn't part of that collection

• Collection variables

  • Declared within the collection scope of your workbench in Postman

  • Directly translate to collection variables in the Collection format 

  • Always included in the exported JSON

• Environment variables

  • Enable you to scope your work to different environments

  • For example, development, testing, or production

  • One environment can be active at a time

  • The active environment determines what variables you can use within your collection

  • If you're using a collection variable, this variable isn't included in the variable declaration of your exported collection JSON - however, there are places in the exported collection that reference where this variable was being used

Cookies 

• Cookies are not part of the request object in the Collection format

• When working with cookies inside Postman, you can add them to the headers using the cookie key

Scripting 

Capabilities of scripting 

• External referencing

  • Scripts written in Postman are typed and authored in the script or pre-request tab

  • When exported, they're placed in the exec field of a script object as an array of strings

  • The Collection format provides you with an extra option for referencing external scripts using src

• Scripts as arrays

  • When you export a collection that has a pre-request or test script in Postman, the JavaScript code is split into an array at each line break

  • This makes it easier to manage version control on the exported script

• Multiple scripts

  • In Postman, a collection or a request can only have one pre-request and test script pair

  • While they look like a pair, in the Collection format, they aren't a pair

  • They are instead separate events in an event list

  • The event list can have more than two events 

  • Postman specifically limits usage to two events per collection or request - however, the event list can accommodate more pre-request and test scripts

protocolProfileBehavior

When you export a collection from Postman, you might see protocolProfileBehavior

• The schema doesn’t say much about this property, but it’s used as a set of configurations to change the usual behavior of a sent request

Protocol Profile Behavior

https://github.com/postmanlabs/postman-runtime/blob/develop/docs/protocol-profile-behavior.md

• These are configs that alter the usual behavior of sending requests 

---

---

Reference

https://learning.postman.com/collection-format/reference/collection

The full API Reference specification for Postman Collection Format

• This includes all the keys and properties for all the individual objects

Objects

• Collection

• Authorization

• Auth Attribute

• Certificate

• Certificate List

• Cookie

• Cookie List

• Description

• Event

• Event List

• Header

• Header List

• Info

• Item

• Item Group

• Request

• Response

• Script

• URL

• Variable

• Variable List

• Version

• Proxy

• Protocol Profile Behavior

---