The collection is one of the most important and most underappreciated artifacts in the entire API world, and I’ve spent years arguing that it deserves to be understood as a first-class citizen alongside the API definition itself. A collection — a Postman collection, a Bruno collection, an Insomnia export, the emerging OpenCollection — is a portable, executable bundle of API requests, complete with the environmental context needed to actually run them. Where an OpenAPI definition describes what an API can do, a collection captures how the API is actually used: real requests, with real authentication, real examples, real sequencing, ready to execute. This distinction matters enormously, because the collection is where API consumption actually happens. The collection is the contract in motion, and for a huge amount of practical API work, it’s the more meaningful artifact than the static definition, because it reflects what people are really doing rather than just what’s theoretically possible.
The definition I’ve worked hardest to establish is the collection as a single, quantifiable, shareable, executable unit of representation for any digital capability — and I mean each of those words precisely. I wrote this in 2019, and it’s the most complete articulation I have of what a collection is. Quantifiable: you can count and measure it. Shareable: you can hand it to someone and they can run it. Executable: it doesn’t just describe the API, it runs against it. And it represents a digital capability — a real thing you can do. This makes the collection a genuinely new kind of artifact: not documentation, not a definition, but an executable, portable, shareable representation of a capability that anyone can run. Breaking collections down into meaningful units of compute, which I wrote about in 2018, extends this — the collection isn’t just a bundle of requests, it’s a unit of computational work that can be executed, scheduled, and composed.
The OpenAPI-versus-collection relationship is the conceptual heart of understanding collections, and I’ve articulated it carefully. I wrote in 2019 that OpenAPI is the static truth and Postman collections are real-world derivatives of that truth, and expanded it in 2022: OpenAPI is your source of truth, and collections are derivatives designed for specific business outcomes. The OpenAPI definition is the canonical, complete description of what the API can do — the static truth. The collection is derived from that truth but shaped for actual use: it reflects how a developer applies the API, with environments, auth, examples, and sequencing baked in for a specific purpose. The relationship between OpenAPI and collections, which I explored in 2021, is one of source and derivative: the definition is the authoritative contract, and collections are the executable, purpose-built applications of that contract. They’re complementary, not competing — you need the static truth of OpenAPI and the executable, real-world derivatives that collections provide.
The collection as a unit of the API economy is a more ambitious framing I’ve developed, and it points at the collection’s deeper significance. I wrote in 2015 about Postman collections as a unit of measurement for transactions in the API economy — the idea that if the API economy runs on transactions, the collection is a way to quantify, package, and exchange those transactions. The collection bundles up the requests that accomplish something valuable into a measurable, shareable, executable unit, which makes it a natural currency for the API economy. This is why the collection became central to onboarding, to documentation, to testing, to so much of practical API work: it’s the portable unit that carries a usable capability from one party to another. The “Run in Postman” button that lets a developer go from reading about an API to executing it in seconds works precisely because the collection carries everything needed to make that capability immediately usable.
The collection format itself has become an arena, which tells you how central collections have become. The emergence of Bruno, with its Git-native, local-first collections, and the OpenCollection specification that extends the Bruno collection, reflect the collection maturing into a standardized artifact the way the API definition did. I wrote in 2024 about Git being how you run in Bruno — collections living in Git repositories rather than cloud workspaces, version-controlled like source code. And I wrote in 2026 about the difference between the Bruno collection and OpenCollection — a flat, simple, Git-friendly Bruno collection on one end, and a more enterprise-oriented, modular, extensible OpenCollection on the other, adding broader protocol support, richer auth, and structured assertions. That we’re now standardizing the collection format the way we standardized the API definition shows that the collection has become as important an artifact as the contract itself — a portable, executable representation of capability that deserves its own specification and its own tooling ecosystem.
Where I keep landing on collections is that they’re the executable, human-centered counterpart to the machine-readable definition, and that they belong at the center of how we think about API consumption. The OpenAPI definition is the contract; the collection is the contract made runnable and shareable for real use. For producers obsessed with their definition and their documentation, the collection is the artifact that meets consumers where they actually work, carrying a usable capability they can execute immediately. For the broader ecosystem, the collection is becoming a standardized, version-controlled, portable unit of capability — the thing you hand someone so they can do what you can do. And in the agent era, the collection takes on new significance, because an executable bundle of requests with all the context needed to run them is exactly the kind of artifact an agent can consume and execute to accomplish a task. The collection started as a convenience in an HTTP client and grew into one of the most important artifacts in the API world — a portable, executable, shareable representation of a digital capability that sits alongside the API definition as a first-class citizen of how APIs actually get used. Producers who think only about their definition and their docs are missing the artifact where consumption actually happens, and consumers who’ve embraced collections have a portable, runnable unit of capability that the static definition alone could never provide. The collection is where the API stops being a description and becomes a runnable thing, and that transition is one of the most valuable developments in the entire history of how we work with APIs.
References
- Postman Collections As Unit Of Measurement For Transactions In The API Economy
- Breaking Down Your Postman API Collections Into Meaningful Units Of Compute
- Postman Collection As A Single Quantifiable, Shareable, Executable Unit Of Representation For Any Digital Capability
- OpenAPI Is The Static Truth And Postman Collections Are Real-World Derivatives Of That Truth
- The Relationship Between OpenAPI And Postman Collections
- OpenAPI Is Your Source Of Truth And Collections Are Derivatives Of That Truth Designed For Specific Business Outcomes
- Git Is How You Run In Bruno
- API, OpenAPI, Collections, Docs, Explorer, Playground, Clients, SDKs, And Integrations
- What Is The Diff Between Bruno Collection And OpenCollection
