Epistemological

API governance is, at its root, an epistemological problem — a problem of knowledge. Before you can govern an API, you have to know things about it: what it does, where it lives, what it promises, whether it keeps those promises, who owns it, what it depends on, and whether the version you’re looking at is real or aspirational. Most governance failures are knowledge failures first. You can’t enforce a standard on an API you don’t know exists. You can’t validate a contract you can’t locate. You can’t trust a definition you can’t trace to its source. I’ve come to think of a huge portion of my API governance work as fundamentally about epistemology — about how an organization knows what is true about its own APIs, how that knowledge is captured and validated, and how much of what organizations believe about their APIs is actually true versus merely asserted. The deepest governance question isn’t “what are the rules?” It’s “how do we know?”

The source of truth is the central epistemological concept, and I’ve been circling it for over a decade. An API definition is a truth claim — I wrote in 2014 about the API definition as the truth in the API contract, meaning the OpenAPI document is the authoritative statement of what the API is. By 2017 I was advocating for using the OpenAPI spec as the central truth in stakeholder discussions, because when business and engineering disagree about what an API does, the spec is the artifact you can point to that resolves the disagreement. The source of truth is the epistemological anchor of governance: it’s the agreed-upon, authoritative representation against which everything else is measured. Without a designated source of truth, every conversation about an API becomes a contest of competing memories and assumptions, and governance becomes impossible because there’s no shared basis for knowing what’s correct. Establishing the source of truth is the foundational epistemological act of API governance — it’s deciding where authoritative knowledge about the API lives.

But the source of truth is more complicated than a single file, and grappling with that complexity has been some of my most careful thinking. I wrote in 2019 that OpenAPI is the static truth and Postman collections are real-world derivatives of that truth, and expanded on it in 2022 — OpenAPI is your source of truth, and collections are derivatives designed for specific business outcomes. The most refined version came in 2024, when I wrote about the API source of truth as well as the echoes and overlays of that truth. This is a genuinely epistemological framework: there’s the source truth, the canonical definition; and there are the echoes — the documentation, the SDKs, the mocks, the tests, the collections, all derived from that truth and reflecting it more or less faithfully; and there are the overlays — the layers of specialization and interpretation applied on top. OpenAPI Overlays, which I wrote about in 2025, are literally a mechanism for expressing domain-specific knowledge as a layer over a base truth without altering the base. Knowing what’s true about an API means understanding this whole structure: where the canonical truth lives, how faithfully the echoes reflect it, and what the overlays are adding or changing. Governance has to operate across all of it, which means knowing not just the truth but its entire epistemological topology.

The gap between asserted truth and actual truth is where the epistemology gets genuinely hard, and where most organizations are quietly lying to themselves. An organization’s OpenAPI definitions describe what its APIs are supposed to be. Whether the running APIs actually behave that way is a separate question entirely — and the gap between the documented API and the deployed API is one of the most common and most dangerous knowledge gaps in all of API operations. This is why I’ve put so much weight on evidence. I wrote in 2024 about where the API evidence is, and about searching GitHub and git repos for evidence of the API truth out there — because the spec is a claim, and evidence is what lets you verify the claim. Contract testing is epistemology: it’s the practice of checking whether the API actually does what the contract says it does, closing the gap between asserted and actual truth. OpenAPI as executable, which I wrote about in 2024, is the same instinct — making the truth something you can run and verify rather than just read and trust. Governance grounded in evidence is governance that knows the difference between what an organization claims about its APIs and what is actually, verifiably true.

Provenance is the epistemological dimension that asks where knowledge comes from, and it’s essential to trusting it. I wrote in 2024 about the role of provenance in dealing with API change — because knowing that a definition is correct requires knowing where it came from, who produced it, how it was generated, and whether its lineage is trustworthy. A definition with clear provenance — generated from the source code, committed by the owning team, traceable through git history — can be trusted in a way that an orphaned definition of unknown origin cannot. GitOps-driven API source of truth, which I’ve championed, is partly an epistemological argument: by putting the truth in git, you get provenance for free — every change is attributed, timestamped, and traceable. Provenance is how you know whether to believe what a definition tells you. It’s the chain of custody for API knowledge, and governance that ignores provenance is trusting claims it has no basis to trust.

The limits of what can be known are a real and humbling part of this, and I’ve been honest about them. You have to know where all your APIs are before you can govern them, I wrote in 2018 — but knowing where all your APIs are is genuinely hard, often impossible, in a large organization. I admitted in 2024 that almost nobody will care about, or be able to comprehend, the entire API landscape — it’s too big, too dynamic, too distributed for any single person or system to fully know. By 2025 I was arguing that API discovery, and therefore API knowledge, will need to be contextual and ephemeral — that complete, permanent knowledge of an API landscape is an unattainable ideal, and what’s actually achievable is just-in-time, context-specific knowledge of the APIs relevant to the task at hand. This is an epistemological concession with real governance consequences: if you can’t fully know your API landscape, your governance has to be designed around partial, contextual, continuously-refreshed knowledge rather than the fantasy of complete omniscience. Humility about the limits of API knowledge is itself a governance discipline.

Trust is the epistemological currency that makes any of this usable, and I came to it relatively late but emphatically. I wrote in 2025 that trust is the secret ingredient missing in API discovery — and discovery is fundamentally a knowledge problem, so this is really about trustworthy knowledge. Finding a definition is not the same as being able to believe it. Knowing an API exists is not the same as knowing it’s reliable, current, and honestly described. The whole apparatus of source of truth, evidence, and provenance exists to produce trustworthy knowledge — knowledge you can act on, govern by, and build on. And there’s a power dimension that I’ve insisted on: API visibility and knowledge is at odds with power and control, as I wrote in 2025. Those who control the API truth — who gets to know what’s real, who can see the landscape, who holds the source of truth — hold power. The epistemology of governance is never neutral, because knowledge of APIs is a form of organizational power, and the question of who gets to know is also a question of who gets to govern.

The specification is, ultimately, captured knowledge, and this is the most hopeful part of the epistemology. When most people see an OpenAPI or AsyncAPI spec, they see technology — but I wrote in 2026 that where you see a spec, I see a common language and a common understanding. The specification is the codification of hard-won organizational knowledge: the accumulated, expensive, painstaking work of getting people to agree on what an API does and how it works, frozen into a machine-readable artifact. A spec is knowledge made shareable, transferable, and durable. The knowledge and wisdom packed into agent skills, which I wrote about in 2026, is the same insight extended — the CLAUDE.md and SKILL.md files capturing operational knowledge in a form that both humans and machines can consume. This is the constructive epistemology: specifications and governance artifacts are how an organization knows itself, remembers what it learned, and transmits that knowledge across teams and across time. The spec is organizational epistemology made concrete.

The AI era raises the epistemological stakes dramatically, because now machines have to know what’s true about your APIs too. When an AI agent consumes your API, it relies entirely on the knowledge encoded in your definitions — it has no human intuition to fill the gaps, no ability to ask a colleague what the API “really” does. The agent knows only what the machine-readable truth tells it, which means the quality, accuracy, and trustworthiness of your API knowledge becomes the hard ceiling on what agents can do. And there’s the deeper reduction I’ve written about: APIs reduce everything to a transaction, including, in a sense, knowledge itself — they reduce the rich, contextual reality of a capability to a discrete, callable, machine-knowable transaction. That reduction is powerful and it is lossy, and an honest epistemology of APIs has to acknowledge that what the machine knows about your API is always a reduction of the fuller human truth. Governance in the AI era is therefore an epistemological responsibility: making sure that the reduced, machine-readable truth your agents act on is accurate, traceable, evidenced, and trustworthy. Because in the end, governance is just the discipline of knowing what’s true about your APIs and making sure that knowledge is reliable enough to act on. The rules are downstream of the knowledge. How we know comes first.

Guidance

API Learnings

APIs

API Governance

API Solutions

API Discovery

API Building Blocks

API Evangelist LLC

Epistemological

References

Guidance Details

Explore more

Discover APIs