There are many ways your public API can be deficient. It is these areas I am mapping with APIs.json and looking to standardize with API Commons. The common building blocks of public API operations represent the visible behavior (or lack of) of API producers, but also reflect the behavior (or lack of) API consumers. There is a lot to read in these tea leaves if you take the time. While public APIs are just the tip of API iceberg, everything you need to know about a company can be read in the signals and lack of signals sent via their public API presence, which collectively reflect on the industries they operate within, and the wider API space-—as well as the API service and tooling providers, and the analysts and pundits who preside and preach over this realm.
The most visibly deficient area that is often out of alignment in the world of APIs is between the API producer and consumer. They are two sides of the same API economy coinage. They are dependent, connected, and synonymous. Yet, there are a lot of API producers who hide behind their fire or pay wall, and avoid meaningful engagement with their consumers, only seeking value generation and extraction. There are a number of others who have feedback loops with their API consumers, but only superficially listen to them, believing they have the answer and know best. Then there are some who actually listen, engage with their consumers, and establish the alignment needed between API producer and consumer needed to achieve the optimal velocity needed by both API producer and consumer.
The next most visible deficient area that is almost always out of alignment in the world of APIs is between the technical and business dimensions of being an API producer. APIs are technical, but they depend on business and people alignment to succeed. Technical API producers are more than happy to ignore the people part of things, and are often ignorant of the business realities surrounding their APIs. Business API producers are often willfully ignorant of the technical details, but are owners and stewards of the business realities, and will make or break a business’s APIs. I’d say the misalignment between API producer and consumer is widely visible to many of us in the API space, but the misalignment between API product and engineer resulting in a perpetual divide between business and technical interests is visible, but there is much more denial and less work being done to address this area. I think techno solutionism keeps both business and technical folks properly insulated from seeing the scope of this deficiency.
The evidence of these deficient areas of API alignment can be seen in the contracts we are producing. They are purely technical. The surface area of our APIs are well defined using OpenAPI, GraphQL Schema, AsyncAPI, and JSON Schema, and we have all the necessary visuals and tooling to work with these machine-readable artifacts. We do not have any of this on the business side of things. We know that a change log and road map are essential building blocks for communicating between producer and consumer. We know that a blog, forum, chat, and other feedback loops are essential between producer and consumer. You see no evidence of this in these artifacts. I could keep going. Onboarding, pricing, terms of service, etc. All the business and people side of API operations exist, but they aren’t grounded in the “contracts” we produce to govern our API operations. In short, nobody is aligning the business side of things, and we are just focusing on the technical side of things.
We have the surface area of our REST, GraphQL, and event-driven APIs defined as machine-readable artifacts. We don’t have the onboarding, pricing, terms of service, SLA, and other business surface area defined as machine-readable artifacts. We version our APIs. We don’t version our pricing. We have a change log and road map for the technical details of our APIs, but don’t have a change log and road map for the business of our APIs. We lint and validate our request and responses as part of governance, but we don’t lint the lifecycle, or the documentation, mocking, SDKs, and other elements delivered across the lifecycle. Without it we repeat the business mistakes of our past. Without it we can’t effectively communicate business change with our consumers. Without it the business and technical of our APIs are always deficient and out of alignment.
Honestly, the technology of APIs is pretty easy. It takes a lot of work at scale, but doable. I find the business of APIs pretty straightforward too, as we have most of the building blocks we need to onboard, sell, and deprecate our APIs-—most things are known knowns. It is the alignment between business and technology of APIs that is fucking hard, and exponentially even harder when you consumer the producer and consumer alignment. This ain’t binary zeros and ones. This is messy human and market volatility. It is stuff that is much more difficult to capture via a single schema—-you need many. But we have to do it. We don’t just need consumer feedback on our APIs, we need consumer feedback on APIs alongside the pricing for the API, all captured alongside an OpenAPI contract so we can map to a specific path or operation. We need that level of granularity regarding the business and technology of our APIs, from both the producer and consumer perspective.
I do not see any API service provider, tooling maintainer, or specification catering to what I speak of here. Commercial and open-source offerings are focused 85% on the technical side of things. Some enterprises are waking up to the need for alignment between product and engineering. This was the top message I received from my 100+ guests on the Breaking Changes podcast. I see a lot of talk about the need for a focus on APIs as a product, but I just don’t see a lot of substance when it comes to services and tooling enabling this alignment between business and technical groups within the enterprise. I’ve read two books from friends on what is needed in the last year—-we have the answers we need. We just don’t have the open source specifications, process, services and tooling to back it up. This is a problem. I see some educational resources emerging around it, and I see some API governance speak of a need to align and standardize, but not much in the way of doing it at scale within the enterprise. These deficient areas of API alignment present between API producer and consumer, as well as the business and technology of APIs will continue to be the biggest challenge doing ANY business in coming years.
