API Evangelist

Subscribe
Archives
April 7, 2025

Weekly API Evangelist Governance (Guidance)

Let’s give a big Monday shout out to our documentation partner Theneo and our SDK partner APIMATIC. API Evangelist storytelling occurs because of Theneo and APIMATIC, and I am thankful to have their support for this exciting ride!

The liminal space as defined by API artifacts like APIs.json, OpenAPI, and JSON Schema are the engine of the API economy, no matter what applications are being powered by those APIs. I didn’t realize just how important this space would become once the power of the enterprise began to shift from the database to the API gateway, and more specifically, once API gateways began to be configured by API specifications.

A filtered image of the statue in front of the Supreme Court
What is you are governing when you say “API Governance”?

As I speak with more enterprises this last week I realize there are many interpretations of what API governance is, and you will need to have an agreed upon definition of what API governance before you will be able to make any movement forward. As I work with teams on this definition, I am realizing that most mainstream enterprises will need to lead with a code-first approach to APIs, and you will need to help teams understand why they need to generate and OpenAPI when they have already invested in their code frameworks.

A filtered image of the Berlin Wall
YAML bridges product and engineering when defining APIs

I encountered some folks during a conversation this week about APIs who were poking fun at JSON Schema being defined as YAML—I reminded them that they have been editing JSON Schema using YAML for the last couple of years via OpenAPI. In another conversation I helped someone I’ve known for a while with some high level thoughts on where I’ve seen the most pitfalls when it came to SDK generation using OpenAPI.

A filtered image of a dragon in the desert with sunbeam over the top
Where good APIs go bad!

Staying within my lane I did some writing this week to continue placing Model Control Protocol (MCP) in the wider context of our API toolbox, and also provided feedback on another API repository proposal that overlaps with what I am doing with APIs.json, but also intends to be some sort of broker with the MCP realm. As we think about this expanding dimension or more likely an API specification land grab, I think it is important to remind ourselves of where good APIs go bad, and continue to think deeply about and engage in conversation around the ever evolving API specification landscape.

The APIOps Business Canvas
APIOps Cycles Canvas Creator

At the other end of the API specification space I was playing with the APIOps Cycles Canvas Creator which allows you to do the important work to define the business operations surrounding your API. I added ten APIOps canvas property types to an APIs.json index for a product API I use to drive conversations and tell stories, but then also crafted some governance rules that could be use to automate the governance of APIOps across many APIs. The goal of this work is to guide some immediate conversations, but also drum up more work helping enterprises bridge the product and engineering sides of the equation.

If you need API Evangelist to help out with API governance please let us know how we can help. And thank you again to APIMATIC and Theneo for their continued support. If you are interested in sponsoring our work and site please review out sponsorship package, and drop me an email today.

Don't miss what's next. Subscribe to API Evangelist:
Powered by Buttondown, the easiest way to start and grow your newsletter.