Weekly API Governance (Guidance)
My name is Kin Lane—I am that API Evangelist guy who has been paying attention to the technology, business, policies, and people of APIs since 2010.
I am in full “code mode” this last week, APIfying all the tools I’ve built over the last year for profiling APIs, standardizing these API-driven capabilities for continuing to profile APIs for APIs.io, but also use them to map and govern the enterprise API landscape for my customers.
There were a few architectural hurdles I needed to get over before I got to work developing my own APIs this last week, but those are out of the way and I am cranking out 4 or 5 new API operations a day to power my new API Evangelist platform. As always my stories are guiding this work, but I struggle to write words and coherently stories when in my VSCode working with the digital bits.
Stories
I am not writing as much as I normally do because it isn’t easy to find the storytelling inspiration while deep in the code realm, but one area that always motivates my writing is sharing stories about the mundane aspects of our operations, like deprecating APIs at the U.S. Department of Labor. And I am using another story about nobody caring about the overall API landscape to ground my new API governance platform work, which is inspired by my favorite complex system—the MTA transit platform kiosk providing you only what you need in any given moment.
Conversations
I had a conversation with Subramanian Krishnan, Architect and API Integration at Cloud Software Group within Citrix about cloud pricing and delivering what our customers actually need—”Subu” is always good for a pragmatic conversation about where the enterprise stands with technology.
Later in the week Lorna Mitchell, VP of Developer Experience at Redocly joined me to talk about the Redocly CLI. I always look to Lorna for an expert view on API specifications and governance rules, expanding my own understanding of what is powering the API lifecycle and governance today, and tomorrow.
Guidance
I am working my way through each of the 75+ API governance policies I use, ensuring they are doing the work to bridge the technical rules and the guidance for teams producing APIs. I started this week at ground zero, with the policies, rules, and guidance for naming your APIs — which seems overly simplistic at first glance, but when you’ve profiled hundreds of APIs all named “Swagger UI”, and argued with developers during API reviews about going beyond REST API from Database, you begin to realize it is where you want to start when it comes to API governance (guidance).
Services
API policy work is one of the primary services I will be offering to customers looking for API governance. Most will not come looking for policy services, they’ll be looking for Spectral or other rules development. But, once I show them how an API policy-driven approach will help them align API operations with wider business operations, they’ll understand the importance of my API policy services.
Discovery
I’ve got the kiddo profiling APIs for me while they are still job hunting after graduating from University. I have them searching many different key words for any evidence of APIs, using a simple bookmarking tool that adds APIs to GitHub as issues. Once submitted I automate the creation of an APIs.json and OpenAPI, but then manually deliver a simple and formulaic blog posts for each one.
There were about twenty other APIs profiled this last week, but I think the Wolfram Alpha LLM and FBI Most Wanted APIs stood out the most. My kiddo like the FBI API and I liked the LLM API. My kiddo will keep helping me profile APIs and providing me with an compelling outsiders view of what is interesting and what is not to Gen Z.
The API Commons
To support my work on developing the APIs.io Search API I published a use cases schema to the API Commons. I am using the schema to align each individual API operation as defined by an OpenAPI with real-world human use cases of the API. This is just one example of how I am aligning the business and technical sides of things using APIs.json, OpenAPI, and API Commons schema.
I am working on multiple machine-readable schema like the use case schema that will help me better provide ways that API product managers will be able to use to configure APIs across the API lifecycle—helping business stakeholders better govern (guide) teams who are producing APIs.
Reading
I am adding a new section this week to showcase what I am reading. I will be using secret management and rotation using AWS Key Management Services (KMS), and how often should you automatically check your site and configure heartbeat and synthetics checks for your API to craft some new API guidance for key management and API monitoring. My friend Adam shared an excellent walk through on rapid prototyping a lightbulb API — a very “illuminating” story. And I continue with my never ending API versioning education with Darko’s Thoughts on dealing with API versioning. I’ll be slowly working in other interesting reads from my week, but don’t expect that I’ll ever get back to the levels I was curating things in v1.0 of this newsletter.
Doing the Work
There is so much work to be done in governing HTTP APIs. My policy, rules, and guidance for the naming of your APIs is just one of 75 policies that are associated with the 415 rules I have in my baseline API governance definition—this means that I have 74 more posts ahead of me. ;-)
I love this work, yet I am afraid that many others don’t.
I think this is why AI is so compelling, and while there will be many aspects of API operations we will be able to be automated using AI, it will still require domain and API strategy, policy, rule, and lifecycle level expertise. One AI footnote from this week is that I see that ChatGPT is getting better at producing accurate OpenAPIs from a copy / paste of the documentation for any single API I am profiling—I will run more tests to verify this in coming weeks.
I am confident that the API Evangelist approach to API governance (guidance) will help make it easier to govern how we produce and consume APIs, but also iterate upon and evolve the API strategy, policies, and rules that define our API operations. It will be January before I get all the work done that I need to demonstrate this, but will keep carving off simple stories to help keep sharing what is going on behind the scenes, but also help me find my way forward to something valuable to my audience and customers.
