Postman Collections As API Contracts

Kin Lane

October 24, 2019

If you follow the API sector, you may have heard the phrase “API contracts.” Many people refer to machine-readable API definitions like Swagger, OpenAPI, Postman collections, or RAML as API contracts. This is in reference to the details at the surface, with the underlying schema acting as a business agreement between provider and consumer. While machine-readable API definitions provide a good foundation for API contracts, here at Postman we feel there are some additional elements required to truly transform a definition to the level of a contract.

Related: Postman Collection best practices

The foundation for an API contract at Postman is always the Collection. Collections provide a machine-readable format for organizing API requests into portable, shareable, and executable representations of one or more APIs. Postman collections help you craft each API request, describing the host, path, parameters, headers, and other details. You can then execute the request, and save it within a folder or collection. Capturing a single API call like this allows you to run, share, and collaborate around it. This replicates what you can do with other API definition formats like OpenAPI, but you can take things even further by defining workflows across multiple APIs—providing two distinct types of Postman collection.

• API Reference Collections – Behaving much like other API definitions, reference collections describe the surface area of each API, allowing you to define the host, paths, parameters, headers and other elements, detailing each digital resource being exposed, and providing a reference for the base value of each API.
• API Workflow Collections – These collections contain everything in reference collections, but are rounded off with environment variables providing pre-populated headers and parameters to deliver specific outcomes, then also chaining multiple API calls together into a more meaningful business workflow.

A Postman API contract provides a set of reference requests, detailing the core of what the API contract delivers, but also workflow collections that demonstrate the actual business value. An example of this in action could be three reference requests in a folder for products, shopping cart, and orders, where there is also a set of workflow requests for searching for a product, adding it to a shopping cart, checking out, making payment, and obtaining a receipt. Postman collections can contain the core references for the API contract, but also provide much more detail that actually puts the business agreement into it. This goes beyond the common definition of what an API contract is, but we feel the added business details aren’t enough, and that you should be able to demonstrate the value by saving an example of each API request. These examples can be used to publish mock versions of the API contract.

• API Examples – Collections allow you save the response for each request as a JSON example, which can then be used to enrich API documentation, and be leveraged to mock each of the APIs included in a contract.
• Mocking APIs – You can use the details of each API request in a collection together with the examples saved for each, to publish a mock version of the API contract, demonstrating the business value being delivered, and quantifying what is expected.

API examples and mocks provide us with a very detailed and functional representation of what each API contract should provide, allowing the definition to be used by stakeholders who can play with and understand the functionality that exists behind each API contract. This allows humans to validate the details of a contract, but more importantly to also deliver what is needed to automate the validation of each request made, as well as the resulting response—making sure a contract is truly being upheld.

• API Pre-Request Scripts – Postman allows you to define JavaScript functions that can be run with the initiation of each request in the collection, validating inputs, performing transformations, and other things you might want to see occur before an API contract is engaged.
• Test Scripts – Postman also allows you define JavaScript functions that can be run after each request is complete, testing that the details of each response meet the minimum requirements set forth in the API contract, and providing validation.
• Runners – Postman allows you to set up runners that will take the collection for an API contract and manually run it, or automate the execution as part of CI/CD pipelines, allowing for validation of API contracts as part of each code release.
• Monitoring – Postman also allows you to take each collection and run it on a schedule, monitoring that each API contract is being met on a regular basis, ensuring that contracts aren’t broken and the business needs of stakeholders are met.

Postman scripts, runners, and monitors allow contracts to be validated by humans, as well as other systems, on a regular schedule. Postman collections allow you to not only make the technical details of the contract available, but also to demonstrate the business value of an API contract, and automate its validation over time. This can be run in multiple geographical regions, and by independent auditors and stakeholders, ensuring the API contract is respected. While this pushes us well into true API contract territory, we feel one more set of elements will help round off our definition of what an API contract should be, ensuring that the contract is approachable, readable, and easily executed by anyone who is given access to it.

• API Documentation – Postman collections can take an API contract and publish HTML documentation that describes the surface area of each API, including the business workflows, and examples of each request and response—allowing humans to onboard and learn what is possible.
• Run In Postman Button – Finally, the Run in Postman button is available on documentation and for embedding anywhere an API contract is referenced, allowing anyone to click, load in Postman, and fully explore every detail, evaluating everything in place to help ensure the contract is fully realized.

This completes our definition of how we view API contracts at Postman. We feel pretty strongly that representing technical details of an API in a machine-readable format is not sufficient to be considered an API contract. We believe you also need examples of that contract in action, and to be able to automate testing and monitoring of what is being promised. A contract should not only contain the machine-readable automation, but also the human readable, shareable, and usable aspects. This approach to defining API contracts makes them accessible not just to developers, but also to business stakeholders, ensuring that API contracts are something everyone involved can understand—and that establishes trust and confidence. We look forward to further discussions around contracts within the API community.