Artifacts are the machine-readable definitions that make the modern API lifecycle possible. When I talk about an artifact, I mean a structured, machine-readable document that describes some dimension of an API — its surface area, its data model, its workflows, its rules, its terms — in a format that both humans and machines can read and act on. OpenAPI, AsyncAPI, JSON Schema, APIs.json, Arazzo, Overlays, Spectral rules, Postman Collections: these are the artifacts. They are the single most important reason the API space has been able to automate as much of itself as it has, and I’ve spent the better part of fifteen years arguing that they belong at the center of how we operate.
The core idea, which I’ve returned to over and over since around 2014, is that a machine-readable definition is the source of truth. I wrote in 2017 about using an OpenAPI spec as the central truth in stakeholder discussions, and that framing captures the whole philosophy: the OpenAPI definition is a contract that humans can follow and that can simultaneously drive almost every other stop along the API lifecycle — deployment, mocking, management, testing, monitoring, SDKs, documentation, and more. Before machine-readable artifacts, every one of those stops was a separate, manual, human-mediated translation of the same underlying API, and every translation was an opportunity for drift. The artifact collapses all of those translations into derivations from one truth.
The relationship between artifacts is where it gets interesting, and I worked this out partly through the lens of value and measurement. I wrote in 2015 that Swagger represents the API value possible, Postman is that value readied as an executable transaction, and a HAR file could be the evidence that the value actually occurred. That progression — possibility, executable unit, evidence — describes how artifacts carry an API through its lifecycle. The OpenAPI is the promise of what’s possible. A Postman Collection is a machine-readable representation of that value, ready for execution, that you can load into Postman or any other system. I later framed OpenAPI as the truth of what is possible and Collections as derivatives of that truth, designed for specific business outcomes. The artifacts aren’t competitors; they’re layers, each one closer to actually doing something with the API.
This is why I kept describing artifacts as units. A Postman Collection is a quantifiable, shareable, executable unit of representation for a digital capability. The “Run in Postman” button turns an artifact into the smallest executable unit you can hand someone — click it and the capability runs. That unit-of-measurement framing matters because once your API is expressed as a machine-readable unit, it becomes something you can count, share, compose, test, and transact with. An API that only exists as prose documentation and a running endpoint is not a unit of anything. An API expressed as a complete set of artifacts is a quantifiable object that tooling can operate on at scale.
JSON Schema turned out to be as important as the OpenAPI surface description itself, and I said so in 2016. The schema of each API response is just as much what people are looking for as the description of the API’s endpoints — because the schema is what gets mapped to other systems, tools, and services. The surface area tells you how to call the API; the schema tells you the shape of what comes back, and that shape is what every downstream system actually needs to integrate. A complete artifact set includes both, because the data model is half the contract.
The lifecycle framing is the payoff. I wrote an extended series on API lifecycle basics where the recurring point was that no stop should be static or hand-built — every one should be driven from artifacts. Documentation should not be a static page; it should be generated from OpenAPI and JSON Schema. Mocking should be generated from the definition. Tests should be built from the existing artifacts, and the tests and assertions should themselves live alongside the OpenAPI as artifacts. This is the definition-driven lifecycle, as opposed to the code-driven one — you define first, in artifacts, and the artifacts drive design, mocking, deployment, management, monitoring, testing, and documentation. I described treating my own API infrastructure as API-first as a recursive loop: APIs being APIs, with artifacts describing the very tools that manage the artifacts.
APIs.json is the artifact I built to index all the other artifacts. Where OpenAPI describes a single API’s surface, APIs.json describes an entire operation — pointing to the OpenAPI, the JSON Schema, the documentation, the pricing, the terms of service, the SDKs, the support, the collections. I came to think of it as an operational fingerprint for a public API: the vocabulary of APIs.json properties acts as both an index and a scoring mechanism, letting you identify and classify API providers by which artifacts they actually publish. It also let me extend machine-readability beyond the technical surface into the business and legal dimensions — machine-readable terms of service, machine-readable pricing — so that the governance and commercial reality of an API could be processed the same way the technical contract was. The complete profile of an API operation is OpenAPI plus Postman Collection plus APIs.json index, three interlocking artifacts that together describe what an API does, how to run it, and where everything lives.
The specification timeline tells the story of artifacts maturing into a stack. I laid out fifteen years of it: Swagger in 2011, OpenAPI as it became in 2015, Spectral around 2018, Arazzo in 2021, Overlays in 2024. Each addition filled a gap. OpenAPI and JSON Schema describe the contract. Spectral and Vacuum rules are artifacts that validate other artifacts — machine-readable governance, your design guidelines expressed as rules a machine can enforce against every definition. Arazzo describes workflows, the multi-step orchestration of API calls that a single OpenAPI can’t capture. Overlays let multiple stakeholders contribute to a definition without all editing the same base document, layering changes on top of the source artifact. The result is a layered artifact ecosystem where contract, validation, workflow, and enhancement each have their own machine-readable home.
The contract framing is the human-facing side of all this. I defined an API contract as a shared understanding of what the capabilities of a digital interface are — human and machine-readable at the same time. That dual nature is the whole point. The artifact is precise enough for a machine to generate code, mocks, and tests from, and clear enough for a human stakeholder to reason about in a planning meeting. This is what makes artifacts the foundation of the contract-first and design-first movements: you agree on the artifact before you write the implementation, and the artifact becomes the shared agreement that the business, the producers, and the consumers all work from.
Artifacts are also where the current AI and agent moment lands. When people ask how to prepare their APIs for AI agents, my answer has consistently been: publish the artifacts. OpenAPI, JSON Schema, APIs.json, Arazzo, Overlays, validated with Spectral rules. An agent can’t reliably reason about an API it can only read as prose. It needs the machine-readable contract, the data schema, the workflow definition, and the index that ties them together. The same artifacts that let a mocking tool generate a mock let an agent understand what an API can do and how to invoke it. I’ve been skeptical of a lot of the AI hype, but I’ve also been clear that the artifacts I’ve been advocating for all along are precisely what makes API integration with AI tractable. The agentic moment didn’t invent a new requirement — it raised the stakes on the artifact discipline that was already the right way to operate.
By the 2020s I was also watching the politics of artifacts. Enterprises had become enthusiastic consumers of OpenAPI, JSON Schema, Spectral rules, and the rest — but reluctant to share them, treating their artifacts as intellectual property and keeping them locked inside the organization. That reluctance is itself a sign of how valuable artifacts had become. When the machine-readable definition is the source of truth that drives your entire operation, it stops being mere documentation and becomes one of your most strategic assets. That’s the whole argument, really. Artifacts are not a byproduct of building an API. They are the thing you should be building first, the unit of truth that everything else derives from, and the foundation on which automation, governance, discovery, and now AI integration all stand.
References
- Swagger Represents The API Value Possible, Postman Is Unit Readied As Transaction, And HAR Could Be Evidence Of Value Actually Having Occurred
- The JSON Schema Is Proving To Be As Valuable As The OpenAPI Spec
- Using An OpenAPI Spec As Central Truth In Stakeholder Discussions
- Definition Driven API Lifecycle Instead Of Code Driven APIs
- What Is An API Contract
- OpenAPI Is Your Source Of Truth And Collections Are Derivatives Of That Truth Designed For Specific Business Outcomes
- An Operational Fingerprint For A Public API
- Fifteen Years Of API Specifications
