I was fascinated with the rise of JavaScript as a ubiquitous but loose client-side programming language in our browser, but then also the introduction of it on the server-side with Node.js. I see a lot of parallels between the ubiquity and utility of JavaScript, and the ubiquity and utility of web APIs. I am equally fascinated by the rise of TypeScript in this fast and loose reality, bringing more discipline to the JavaScript programming realm. Using TypeScript as part of my work around Spectral rules governing APIs has left me thinking more deeply about the potential of not just strongly typed APIs, but strongly typed API operations surrounding our APIs across the enterprise.
OpenAPI provides us with the scaffolding for mapping out the surface area of our web APIs, getting us on the same page regarding the business and technical details that make the API deliver the value it does. AsyncAPI provides us with the same scaffolding for mapping out the surface area of our event-driven APIs, also helping us get on the same page when it comes to delivering real-time value. Spectral rules allow us to define rules that govern the seemingly endless nitty gritty technical details of our OpenAPI and AsyncAPI contracts—-this is the current frontline being defined and shaped across enterprise organizations and API service and tooling providers today.
For the last couple of years, as I stoke the development of rules to make our API definitions more strongly typed with Spectral, I have been investing in doing the same for the lifecycle and the platform underneath these API operations. The reason I know I am onto something is that there are numerous folks who tell me what a dumb idea this is and push back on my introduction of exploratory schema for defining the API lifecycle and mapping out the infrastructure and tooling already in use across our API operations. I’ve grown accustomed to the people who don’t have the time or creativity to understand what I am talking about, telling me this will never work, and that nobody will care about this. Which just provides me with the signals that I am a few years ahead of things—-it is all good, in 2027 API service providers will be like–“look what we’ve invented!!”.
All I am proposing is a shared schema for describing our API operations. Just like we’ve developed a shared schema for our synchronous and asynchronous APIs with OpenAPI and AsyncAPI—validated with JSON Schema. I am not talking about one operation to rule them all. I am just talking about a standard set of properties we use for describing how we define, design, develop, deploy, publish, distribute, test, secure, observe, and onboard with our APIs. Each enterprise will approach these aspects of API operations differently, but like web and event-driven APIs, there will be more common patterns than you imagine. One thing I’ve learned through watching OpenAPI and AsyncAPI evolve is most of the differences between our APIs were just different perceptions, words, and programming language dogma, not actual differences, and these open-source artifacts have helped us get on the same page. Developers resist standardizing how we talk about APIs, and developers resist standardizing how we talk about API operations.
I am endlessly fascinated by how developers embrace discipline and structure within the programming language realms they’ve bought into, but resist standardizing and the introduction of discipline and structure at a higher level across programming languages (OpenAPI, AsyncAPI, JSON Schema), as well as how we operate together. When you look at the handful of API lifecycle standardization discussions and diagrams I’ve led over the world, you see the evidence of this developer resistance. Opinions. Beliefs. Dogma. All blocking the road forward when it comes to getting us on the same page and stabilizing the API factory floor and digital supply chain for the next generation of applications, integrations, and artificial intelligence. I love it when a senior developer tells me how much I don’t understand about their strongly typed continuously deployed programming world, as I work to introduce similar patterns into the operations around them. Resistance!!
Almost every time I map out the API lifecycle around a developer, they tell me that what I am proposing is a waterfall, and is too much—nobody is going to do that. Ummmm, that is just a landscape map that reveals what is already around you. I am not inventing a thing, just mapping the API operations already in place. You just can’t see it. You are just in denial of it. As soon as I share the landscape with someone who is elevated enough within an organization, they are almost always, “YES!!!” They see it. Then they are immediately filled with dread regarding how they will get others to see this, understand it, let alone collectively follow and embrace it. Before we can get to a place where our API operations, factory floor, and supply chain are strongly typed, we have to map it out. We can’t define any rules to govern what we can see and define. As it stands today, our API lifecycle and operations are being defined by API service providers and industry analysts, and not by those on the ground floor of API operations. If we are going to begin moving the needle forward, someone is going to have to be the Henry Ford of API operations and do the hard work to define how it is we do what we do, and then automate and streamline the chaos into something more coherent and shared.
You can play around with some of my thoughts on this area using my APIs.json governance playground where I explore playing around with a strongly typed set of publicly available API products, but also the dance that occurs with product, engineering, and platform teams to get these products out the door.
