The gateway for moving towards an API contract focus with API Evangelist was the discovery of APIs and trying to figure out how to make APIs more visible to business stakeholders. API discovery is the one area of the API economy I consider myself an expert, as I’ve been studying since about 2012, and have been working to evolve my APIs.json discovery specification since 2014. While looking for solutions to the API discovery problem, I concluded that very few people care about API discovery until it intersects with a technical problem they care about like security or observability, and I figured I would need to find more of the business reasons that intersected with API discovery if I was going to move the API search and discovery conversation forward in any meaningful way.
After stewing in all the technical and business reasons why people end up pretending or genuinely caring about API discovery, I concluded that I had to find the reasons that matter to business stakeholders when it came to not just the discovery of APIs, but the visibility of APIs. I find the technical reasons why people care about discovering APIs to be too skewed by two main things, 1) developers only care about discovering APIs when it interests them which is rarely in alignment with overall business strategies, and 2) vendors inflate API discovery solutions and discussions to match the latest investment trends and their interests. These two realities and a lack of any assessment of why API discovery from a business perspective leaves us with the API sprawl and chaos that exists today. I concluded that there was no way I’d get technical stakeholders to care about producing an APIs.json for their APIs. The uphill battle to convince technical stakeholders to create an OpenAPI for their APIs has taught me that they will be unreliable narrators of the operational and business contract for the APIs they are creators or stewards of.
APIs.json was born as an API discovery format that you could publish in the root of your API portal. It still is this. However, I envision APIs.json as an API discovery format that could be published into the root of any Git repository as well. It is nice thought that all APIs should be registered with an API portal, either an internal or external one. I also was a big believer in the Postman Workspace philosophy that a private, partner, or public workspace could be the center of API discovery—with or without an APIs.json. Whether you are using Google search, Postman search, GitHub search, or the search on your API portal provided by your API service provider, I still think there will be many, many, many APIs that won’t show up, either that they aren’t published there, or just nobody knows they exist. While I will still evangelize the adoption of API portals, usage of API workspaces, and relying on existing search solutions, I am going to be advocating that instead of creating APIs.json purely for discovery purposes, that you should be creating them for purely business reasons, to understand the business contracts you have in place throughout the enterprise.
I have learned that people don’t care about APIs—business or technical folks. Even most people who say they do don’t. The only time people care about an API is when it supports their business or technical interests. Another aspect of APIs is that people tend to point to the visible distribution or end-result of an API—the desktop, web, mobile, device, or AI application. But APIs are the contract between all of these applications and producers of the resources and capabilities made available via APIs. I want to make APIs as visible as the application they power. I believe this is the only way we will get business stakeholders to pay attention and get involved at every stage of the API lifecycle, but it is also the only way we are going to align the business and engineering interests behind applications. I want to make things about business contracts, and not just about APIs—while still elevating APIs. My answer is API contracts. I am confident that technical folks are going to push back on the idea of API contracts that bridge the business world, and I am confident that business folks will shy away from the perceived technical nature—I will evolve this over time with a steady drumbeat around why alignment on the business and technology of APIs is how we do business in 2025.
Just like API documentation and portals makes APIs more discoverable and visible, I am confident additional metadata like use cases, tags, plans, and other essential API building blocks will make them more visible. I believe that bridging the business and technical divide with policies that speak to business pain and solutions will make APIs more visible. It’s like what all the observability and traceability folks are trying to do from a technical perspective, but I want to do from a digital supply chain, factory floor, and distribution perspective. As a business leader, how do you discover and see how your digital business operates? How do you understand that you can start pulling knobs and levers across the API lifecycle as a business stakeholder and obtain the business outcomes you are looking for. This is what I am doing with API contracts—making API discovery more about seeing how your business operates, and less about developers finding the API they need to build an application, or API service providers just finding their next lead.
