What is API Governance?

One thing I like about this blog format is that I can use the title, “What is API Governance”, over and over. Each blog post has the date timestamped in the title, so It captures my thoughts on the subject over time. Using my blog to work through complex concepts over time is how I govern the velocity of my career, speeding up and slowing down as required, to help me find the signal in the noise. I am the API governance lead at Bloomberg. I have helped define and shape the world of API governance as Chief Evangelist at Postman, my work on OpenAPI, AsyncAPI, JSON Schema, Spectral, and as the API Evangelist. I should know what API governance is, but I know enough to know that this definition is fluid and changes over time. So I am perpetually looking to ask this question and continue to test my understanding along the way.

I like the definition of simply governance on Wikipedia:

“Governance is the process of making and enforcing decisions within an organization or society. It encompasses decision-making, rule-setting, and enforcement mechanisms to guide the functioning of an organization or society. Effective governance is essential for maintaining order, achieving objectives, and addressing the needs of the community or members within the organization. Furthermore, effective governance promotes transparency, fosters trust among stakeholders, and adapts to changing circumstances, ensuring the organization or society remains responsive and resilient in achieving its goals.”

I also like the definition for what a governor is on Wikipedia:

“A governor is an administrative leader and head of a polity or political region, ranking under the head of state and in some cases, such as governors-general, as the head of a state’s official representative. Depending on the type of political region or polity, a governor may be either appointed or elected, and the governor’s powers can vary significantly, depending on the public laws in place locally.”

If you continue reading on in the governance definition, I think that this definition reveals more about what is going on with with API governance, “It is the process of choosing the right course among the actors involved in a collective problem that leads to the creation, reinforcement, or reproduction of acceptable conduct and social order”. However, as we are talking the governance of “state machines”, I think we should be also thinking about the concept of governor when it comes to devices and systems, with “a governor, or speed limiter or controller, is a device used to measure and regulate the speed of a machine, such as an engine.” It is at this intersection I am working to break down the role of API governance in our lives, and help me better understand what is actually being governed here. What are we governing with API governance? APIs? Or are we governing teams producing APIs? Or are we governing the businesses who are producing APIs? Maybe it is about governing the end-users of applications built by developers consuming APIs? I think most technologists are fully under the belief that we are governing the APIs, and more specifically the design of the APIs. Most technologists don’t see the wider business apparatus being governed around them. Most technologists also don’t see the wider human apparatus being governed around them. I’d say this is where challenges really come into focus when you are focused on technical governance on APIs, which are actually the intersection of a huge amount of business and people issues that need governing, governance, and governors. APIs govern business. APIs govern people. Governing APIs is about governing business and people. I wouldn’t proclaim I have all of the answers for doing governance “right”, but I’d say that to at all be effective you have to have a handle on things across these dimensions, or you aren’t going to get anywhere.

API governance is often showcased as about creating Spectral rules that lint API definitions like OpenAPI and AsyncAPI in the IDE, CLI, and CI/CD pipelines. That is the tangible output that many people focus on when talking about API governance. However, the rules are only as good as the people involved, the processes defined, as well as the human and machine readability, automation, and feedback loops that exist across all stakeholders. There is no right way to do API governance, but there are plenty of wrong ways. For me, API governance is equal parts about the artifacts and the process, but is all about the people landscape across the organization and industry where API governance is being applied. In my experience API governance that is just focused on the technical aspects like OpenAPI and Spectral, or the nuance of REST, will ultimately be insufficient. You have to bring in the wider context of business governance, as well as the governance of the people producing and consuming APIs, otherwise you won’t have your finger on the pulse of what is truly needed at the moment.

One of the things I like about the definition of governance and governor above is how one sided they are about the messy human space that is seeking to be governed. I only like this because it reflects the one-sidedness of API governance. Technology likes to ignore the messy human stuff. Business likes to ignore or exploit the human messy stuff. This is why geeks and MBAs partner up so well when it comes to delivering startup solutions. I’d say these definitions touch on things like trust, transparency, and elections—-those critical aspects of governance that make the difference. How API governance actually enables a constituency, and leverages a feedback loop across the tribal factions who are producing APIs, as well as with those who are consuming those APIs will ultimately be what defines the success or failure of API governance across an enterprise. This systemic complexity and human messiness is why I like the Venn diagram of governance and governor over people and organizations as well as with machines. I don’t think we’ve done as much thinking about governance over virtual machines over physical machines, due to their abstract and often unseen nature. This is the moment we find ourselves in. So, what is governance in this moment? We are learning about the physics of this virtual world. It took a lot of experimentation to understand what velocity, heat, gravity, and other physical constraints existed over a century ago, and now we are learning about what those are in the virtual space. Despite popular beliefs, there are limitations to what humans can handle in the virtual world. There are market limits in a digital world that often seem endless. API governance is about the perpetual negotiation between governments, enterprises, and the industries they operate in. API governance will be about defining these boundaries, standardizing what is happening, and enabling the most ideal outcomes from an agreed upon velocity-—the devil of API governance is really in the details of what is agreed upon in any given moment.

APIs are and will continue to be the governor of markets. They will be how we govern velocity and create scarcity and perceived or real value. API governance will be where enterprises govern the change that occurs across the industries they operate in, and absorb or exacerbate the change and velocity of their factory floors and supply chains. Workers will exist above or below the API line, and be defined by whether they are part of governance or just being governed by it. API governance will be defined by how machine-readable and automated it is, but also by the stakeholders at the table and how much voice they have in the process, but more importantly how educated and aware stakeholders are regarding the overall process. As with the governance of societies, enterprise organizations may think that a good API governance dictator will be simpler, straightforward, and less messy, when in reality the more educated, aware, and involved your API consistency is, the more effective and scalable your API governance will be.