Intermediate API Skills: Reference Collections
Postman collections are versatile machine-readable representations of what is possible with an API. As with other formats like OpenAPI and RAML, Postman Collections allow you to define the surface area of an API, providing a definition that can be used throughout the API lifecycle. This allows Postman collections to help developers design, mock, deploy, test, document, and secure APIs with a variety of services and tooling. Collections provide an executable and shareable representation of an API that helps reduce friction along the way.
Many features of Postman collections help drive the development of APIs—similar to OpenAPI—but a few key elements also help developers to be more successful while working with existing APIs, developing entirely new APIs, and moving legacy APIs forward for each new version. The cornerstone elements of reference style Postman collections are as follows.
- Folders – The ability to organize API requests into folders, nesting and organizing them, helps reduce the cognitive load when it comes to getting up and running with an API.
- Verbs – Being able to define GET, POST, PUT, PATCH, and DELETE HTTP verbs specifies the vocabulary nuance of different API paths, allowing each resource to be properly understood and executed as part of a collection.
- Path Parameters – Defining the parameters that are used in the path of each API request provides a dynamic element to returning the results users are looking to receive.
- Query Parameters – Being able to define each of the individual query parameters that can be passed as part of each API request allows users to shape requests to get the data and content they need.
- Authorization – The ability to authenticate with APIs using any of the common patterns, including, but not limited to API keys, OAuth, Basic Auth, AWS Auth, and more keeps API access from collections secure.
- Headers – Allowing API collection creators and users to add and manage the headers that are passed in with each request controls structure and routing, determining how an API is engaged with.
- Body – Providing full control over the body for each request allows the collection creator or user to maximize the ways in which POST and PUT requests are put to use in a collection.
- Cookies – Mimicking the behavior across websites by allowing cookies to be included along with each request acknowledges that APIs are an evolution of the web, and that JSON, XML, CSV, and HTML are relevant responses.
- Examples – Each API request and response can be accompanied by examples which can be used in documentation or mock APIs.
- Comments – The ability to add comments to each individual request allows collection managers and users to annotate APIs and open up a conversation with all stakeholders.
These elements represent the foundation of Postman reference collections, providing many of the same capabilities as OpenAPI, RAML, and other machine-readable API definitions. This allows for interoperability between existing specifications—any user can quickly import Swagger, OpenAPI, and RAML into Postman and automatically have them converted to Postman collections, which can then be published and shared. Postman can then be used as the central source of truth when it comes for defining what an API is capable of, allowing the API definition to generate mocks for each API, publish documentation, and define any testing and monitoring that needs to be realized.
A reference Postman collection is just one of many ways in which you can describe your API using Postman. This approach to using collections can provide a complete reference for every digital capability, offering up a human-and-machine-readable account of all API details in a shareable format that teams can use to learn and develop around an API. Postman collections do not replace API documentation, but they do provide a source of truth that can be used to publish your documentation—keeping everything up to date. Reference collections power the design, development, delivery, and integration of an API in a single definition that can be centrally maintained, while also being widely shared across all stakeholders involved in putting the API to work in desktop, web, mobile, and device-based applications.
