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.
Everything feels in neutral right now. I mean, it feels like we are still barreling uncontrollably into the future, but the transmission isn’t in any specific gear. Maybe it’s the election, artificial intelligence, going into the holidayz, or some other economic and labor weirdness, but everyone seems pretty distracted and rudderless. Whatever the cause, I am taking full advantage of it by focusing on my API work.
It is good to be back as API Evangelist and not have any communications department gatekeeping my work. I get to exercise ye old rant muscles and practice my old fiery versions of evangelism—it will take me time to get back to old levels, but I had a couple of inspirational moments this week. While I think most folks don’t hear me down here inside the system, I still like yelling about what matters in-between the deafening hum of the circuits.
Stories
Words matter, and for last the fifteen years I’ve worked alongside the API community to humanize the acronym API, while also working to make APIs more accessible to non-developers. So, as I re-read the Consumer Finance Protection Bureau’s (CFPB) 1033 rule, I was disappointed to see them deliberately use the phrase “developer interface” instead of APIs. We’ve used API to describe HTTP APIs for 25 years now, and have built inroads with business stakeholders—their choice of words will have a negative impact on further widening the divide between business and technical stakeholders.
With this rant over with, I got back to work showcasing how I am using the open-source Monaco editor to manage APIs.json and OpenAPI, but also the policies and rules I am using to govern these specs. There is a really nice relationship between JSON Schema, Monaco editor, and Spectral rules when it comes to governing (guiding) the management of any common artifact used across the API lifecycle.
With a little bit of work accomplished I got back to ranting, evangelizing how we are all taking the social fabric of HTTP APIs for granted—this is the fabric that keeps everything together and moving forward, without it, the API sprawl will continue to expand exponentially. However, just as I begin using this hyperbolic phrase, like everything, I begin to question whether or not API sprawl is a bad thing, or something that is just being sold to us. Do we really think we are going to be able to tame the API sprawl that exists, or maybe we need to learn to embrace and ride the waves of sprawl.
Conversations
Early on in the week I had an API Evangelist conversation with Ian Mai, Executive ADHD & Impulse Control Coach. Ian and I worked together at Postman, and after he announced he was leaving Postman and tech, I wanted to learn more about what he would be working on. This wasn’t your average API conversation about the technology of APIs, but I think our exploration the role our technology is playing in feeding our addictive behavior is very relevant to this moment.
Continuing conversations with ex-Postmanauts, I had Greg Dennis, Senior Software Engineer at Zeil by to talk about the difference between language library APIs and HTTP APIs. Greg maintains json-everything, a .NET library for working with JSON Schema, as well as helping lead the JSON Schema specification. Greg’s perspective helps me better see the boundaries of my world of HTTP APIs, and I am thankful I was able to work with Greg on JSON Schema, and that he continues his work even after leaving Postman Open Technologies.
Guidance
While working with my kiddo to profile different APIs they had discovered, I produced a simple story about how XML, JSON, YAML, and CSV can represent the same thing, but be expressed in different formats—using a simple address as the example.
After doing all the research on my versioning policies and rules, I stumbled across the fun fact that 5 of the 7 Top API providers were doing versioning wrong—leaving me questioning what the actual “right way” might be, and whether there really is a right way in the first place.
Services
The work on API policies, rules, and guidance this week was focused on nailing down the versioning policies and rules for APis.io. After doing the research I talked about above, I decided to version APis.io using the URI or path, which isn’t the “right way”, but it is the way that makes sense for this particular client of mine.
In preparation for a talk I have coming up about internal API evangelism within the enterprise I spent time updating my API evangelism toolbox, which I will use as the outline for my upcoming presentation. Now that I published this in my newsletter, I am going to go back and edit my blog post to reflect the role this newsletter plays in rounding up the week, and setting the course for the next week.
The API Commons
As I continue to refine the 175 API policies I need to automate API governance, I am learning that I need to get more structured in how I evolve the underlying policy schema, and validating using JSON Schema to make sure I am not breaking things. I like to move fast with the schema I am using to govern APIs, but I have to balance this with not moving too fast and breaking things. To help others reuse my work, I published an example policy, as well as the first draft of the JSON Schema for policies so that you can validate policies while editing or building via CI/CD pipelines. Policies are the connective tissue between the technical details and the business details, guidance, experience, and overall API lifecycle.
Reading
It was a week of exhilarating reading about HTTP headers ;-), beginning with the IETF rate limit header field for HTTP, but then also a story from Zuplo about understanding the HTTP deprecation header. As sleep inducing as these header stories can be, they are critical to the HTTP transport we depend on, and everyone should be doing the work to maintain reasonable HTTP header literacy rates across the API community.
I am exploring new ways of deploying APIs, and the infinite Git repos on Cloudflare Workers caught my attention as a federated way of deploying APIs at the edge. Elon Musk’s X is looking to further squeeze developers with new API fees—not surprising at all, and continues to pile on my my ongoing mourning for what I used to consider the most important API out there.
Speaking of Twitter, as I am working to rebuild the social media presence on Mastodon, Blue Sky, and Threads, I was happy to see the APIs You Won't Hate Blue Sky starter list, showing signs of API life on these new social networks. I closed the week learning more about what it will take for telcos to unlock value from network APIs from McKinsey, a topic I’ve lightly studied for a number of years, and think holds a lot of potential for further standardization and governance.
My Domain Matters
It feels good to have my domain (apievangelist.com) still producing after almost fifteen years. As I watch Twitter continue to burn, Medium struggle with API slop, LinkedIn become noisier, while I also do the hard to work to build up new audiences on Mastodon, Blue Sky, and /threads, I am thankful I kept my domain and have maintained a certain level of activity. Even with all the work I have to do to be heard in a really noisy online world, I am confident that my domain will remain relevant.
My domain doesn’t require massive scale and traffic to produce value for me and my audience. I just need to reach a handful of people who are doing the important work within the enterprise—something that generates leads, conversations, and interest in my work while also adding more awareness around my expertise. This is all I am looking for as I work to generate revenue and value from my API work, and the conversations from this week are exceeding my expectations of what is to come.
Thanks for tuning in folks — see you next week!!
