I use the phrase “source of truth” a lot to describe the authoritative, centralized, up-to-date artifact and discussion surrounding APIs. I tend to consider APIs.json, OpenAPI, and JSON Schema artifacts that are linted using Spectral rules within a GitHub (or other Git) repository. Most technologists believe that the source of truth is in the code running in production, as well as increasingly the gateway runtime. All of these things can be true, and also not be true. The concept of the source of truth is a complex and problematic one that is relative to who you are and where you operate within the API supply, manufacturing, and distribution chains.
We love seeking truth as technologists. Not having the “truth” for any API we are producing or consuming is the top way in which friction is introduced into business operations using APIs. If we aren’t talking about the same thing, there is little chance we will agree on anything and get on the same page. But, agreeing on what the truth is and isn’t, is a very relative thing, and thus continues being very elusive, just like “free beer tomorrow”. Establishing a source of truth, even as problematic as it is, should be a top priority for anyone trying to get a handle on API operations. This source of truth should be the technical, but also the business details of an API throughout its lifecycle, and while you should always strive for that truth to be an honest take of what is happening, you shouldn’t fret over its shortcomings.
I applaud folks seeking the source of truth for an API. I also get why people want to defend what they see as their source of truth. If you write code, it is the source of truth. If you work on the gateway, it is the source of truth. If you are a religious API design-first warrior, OpenAPI is the source of truth. If you live in your Postman client, then collections are the source of truth. The source of truth will always be relative and elusive, but you should always work to establish it, despite it regularly slipping between your fingers or resulting in you clashing with your coworkers. It is important. This is the work. In reality, the truth will reside in many different places that are permanent and ephemeral, and you should gather evidence of that truth throughout your API journey each week. Gather, aggregate, and share this evidence, working to build alliances with others when it comes to what truth matters and what doesn’t matter.
I distinctly remember talking to enterprise architects and technical leadership as Chief Evangelist at Postman who see OpenAPI as the source of truth for any API, but also developers, technical writers, solutions architects, and sales engineers who would see a functional Postman collection as the source of truth. They are both right. I think these differences are more about how it takes a village to do APIs, and that there are echoes of the truth spread all across our API operations for well-meaning and purposeful reasons. People are just trying to get their work done, in the moment and space that is relevant to their world. I think that the new OpenAPI Overlays specification will help contribute to this conversation in some very meaningful ways, while also increasing the sprawl and chaos regarding what is the source of truth. Technical writers will get their own overlay of the truth. People in charge of localization will get their own source of truth. Where the real opportunity lies is if tooling and service providers can assemble and keep their finger on the pulse of where the truth is in any given moment.
Ultimately I believe any solution we adopt to help us with the sprawl and chaos of API operations will have to embrace the gathering of evidence of the truth from all across API operations, from both the producer and consumer perspective. I don’t think there is any permanent source of truth for any API and defining the truth is an ongoing effort. I think that the truth is defined by multiple machine and human readable API artifacts, and APIs.json, OpenAPI, JSON Schema, and other artifacts like log and HAR files, SDKs, snippets, and other elements will need to be regularly mined and interrogated for any evidence of the source of truth. I am hopeful that while very few people love getting hands-on with this work, that services and tooling will continue to emerge to help us do this work during design and development time, but also during build and runtime. As an evangelist I will always be looking for the truth, and I believe that the truth must be both human and machine readable, while reflecting the needs of business and technical stakeholders who are both producing and consuming APIs. The truth is relative, elusive, and ever-changing in API land.
