I have cared about API specs over code for some time now. I have long invested in OpenAPI for defining the surface area of HTTP APIs, APIs.json for defining the surface area of API operations, JSON Schema for validating it all, and Spectral rules for governing it all across the API lifecycle. However, in the last five years I’ve developed stronger opinions about the role that infrastructure, tooling, and services play as part of helping or hurting API governance efforts. Like programming languages, there is a lot of ideology and dogma surrounding infrastructure, tooling, and services. While API specifications are free of some of the same forces, it exists in my smaller doses, and artifacts tend to be pretty modular, portable, and keep moving, where infrastructure, tooling, and services stay put and accumulate or lose power.
APIs.json, OpenAPI, JSON Schema, and Spectral each have their own politics and friction, but also possess a great deal of combined value to moving API operations forward in a consistent way, independent of the infrastructure, tooling, and services they are used in. The JSON and YAML, validated by JSON Schema, and linted throughout the API lifecycle with API governance, provide the life blood of API operations, which can be applied to a wide variety of infrastructure, tooling, services, and custom code. These specifications are the configuration and validation of API operations. This is where I prefer to operate in a federated, outside-in, and bottom-up way. There is a lot more flexibility at the specification layer of API operations, and there is a lot more opportunity to accumulate and mature value that can then be applied across the API lifecycle. Which can be used as an input and hopefully an output of the infrastructure, tooling, and services we depend on for operating our APIs.
I know that most people tend to believe in the power of the UI, but I have seen evidence that the possibilities for the greatest change lie in the standardized artifacts we are using to define the API landscape. Not just the API, but the platform and lifecycle. I’ve had a front row seat of the politics that exist across Swagger, OpenAPI, AsyncAPI, JSON Schema, and Postman Collections. I’ve also had a front row seat to how API management, and other API service providers, as well as their investors view, invest, and play games when it comes to API specifications. I’ve studied the relationship between these API specifications and open source tooling. I’ve seen investors tell their startups to import OpenAPI, but not allow for the export of OpenAPI. I’ve been involved in all of the governance efforts around these specifications. I am carving out a new specs-only approach to API governance that I feel will help me reduce the friction from the politics that surrounds API governance efforts within the enterprise.
I see API artifacts as what defines, configures, and validates our API operations, while potentially gathering value and maturing over time when done well. I believe these artifacts are where I can contribute the most to enterprise API operations. I can then leave it to the enterprise API platform and governance leadership to define where and how these artifacts get used within infrastructure, tooling, and services. I can also help encourage them to use infrastructure, tooling, and services that utilize these specifications, and enable the usage of them as inputs and outputs. I will stay out of decisions regarding how, why, and when infrastructure, tooling, and services are purchased and used, and how artifacts are inputted and outputted from infrastructure, tooling, and services. This is where I prefer to operate and contribute to enterprise API operations, but it is also where I think that API governance should operate in general. In the same way that HTTP APIs designed to be independent of any single programming language, API governance should be independent of any single infrastructure, tooling, and services used across the API lifecycle.
People love their tools. I don’t want to get in the way of that. The enterprise has made investments in infrastructure, tooling, and services. I don’t want to get in the way of that. I am just looking to properly document all of those dependencies across the API lifecycle, and understand how to leverage the API landscape mapped out as APIs.json, OpenAPI, JSON Schema, and governance defined as policies and rules across this infrastructure, tooling, and services. All of my API governance services will be offered as strategic or tactical APIs.json contracts. Tactical API contracts have human and machine readable artifacts like documentation, OpenAPI, SDKs, and plans. Strategic API contracts will have human and machine readable artifacts like guidance, policies, and rules. With these services I am looking to help enterprise API producers and consumers reduce the politics and friction involved with doing API governance at scale with a specs-only approach. Reducing friction at this layer is going to help me be more successful, but also help others benefit from a specs-only approach to API governance.
