Blog

Twilio Uses A PII OpenAPI Extension on Their API

I have been immersed in the profiling of the Twilio API, and as with most of my work, there are stories in the cracks of this profiling. Twilio maintains their own OpenAPI for their APIs, which I prefer to having to create myself. I’d like it if API producers would maintain their own OpenAPI and APIs.json, but I will take whatever I can get. I learn a lot from API producers when they maintain their own Open...

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 gov...

OpenAI Injects Code Samples Into Their OpenAPI Using An Extension

As I was profiling the OpenAI API I noticed they had vendor extensions. This is a common thing I come across while profiling APIs, so I always make sure I spend some time evaluating the approach so that I can better understand why API producers feel the need to extend the spec. Twilio and Stripe both utilize extensions that help track maturity, PII, and other details of API operations that aren’t commonly e...

Making the API Realm Visible and Tangible

I think I am settling in on what I want to be doing for the next 30+ years. I want to make APIs visible and tangible. I enjoy doing API reviews at Bloomberg and feel defining rules that help standardize the public landscape is a meaningful thing to be doing. But I am curious at this moment, how do you make APIs something you can actually see so you can support operations, but also so that you can document this moment as it is passing by. I am already seeing how ephemeral and invisible all ...

API Resource, Capabilities, and Experiences

I am profiling APIs for APIs.io. I started with Twilio and Stripe, and working my way through many more. I am profiling their API operations using APIs.json, outlining their business approach to doing APIs, but I am also making sure the surface area of each A...

Titles, Summaries, Descriptions, and Tags For APIs.json and OpenAPI

I can’t stress enough the importance of providing well thought out and useful titles, summaries, descriptions, and tags for your APIs, taking full advantage of APIs.json and OpenAPI capabilities. I am sorry, but after profiling a couple hundred APIs (recently), and many thousands more over the years, I just don’t understand why API producers phone it in when it comes to providing this vital metadata. If you want to be successfu...

Stripes Monolithic OpenAPI vs. Twilio Modular OpenAPIs

I profiled Stripe and Twilio using APIs.json recently. My API profiling process requires that I get to know an API, and while Stripe and Twilio do not maintain their own APIs.json index, they both do maintain OpenAPI for their APIs-—they just do it differently from each other. Stripe chooses to use one large OpenAPI for ever...

Breaking OpenAI OpenAPI Into 10 Separate OpenAPIs

As I profile APIs for APIs.io using APIs.json, I break up OpenAPIs for providers along base path lines. I prefer distributed sprawl for my Artisanal APIs.json profiling work. I prefer my API representations using OpenAPI to be the smallest unit possible. Like OpenAI’s own advice for crafting OpenAPI for your ChatGPT plug—it just makes sense to k...

Twilio and Stripe Do Not Use PUT For HTTP Resource Updates

The shouts of the RESTafarians in 2010 still ring loud in my head. REST wasn’t just a philosophy, it was a religion. You needed to have read Roy Fielding’s dissertation and posses a strong handle on the four levels of REST maturity, otherwise you were doing IT WRONG!!! Folks rarely demonstrated what they were talking about, and almost always shamed you when you didn’t emulate what they were talking about in your work. Maybe I am just too sensitive, but it was this dogma that pushed me to s...

This Post Is Not About Artificial Intelligence

I love that when I post something as mundane as my coffee drinking on LinkedIn I can muster upwards of 50 reactions to it, but when I post something critical of artificial intelligence I get one or two. I regularly see folks chant that if you aren’t talking about AI, nobody will read it. I don’t give a shit about AI because it doesn’t benefit me in any way (currently). During the last AI wave I pretended to give a shit because I was dependent on being part of the mainstream API chorus. Whi...

Adding OpenAI Plugin Manifest to the APIs.json Properties

I love the meta dimensions of my API work. I am profiling the OpenAPI for inclusion into the APIs.io search engine. To do this I create an APIs.json and add all of the properties of the OpenAI API operations to it. This includes things like getting started, docs, their OpenAPI, terms of service, and other common building blocks. After landing on the Read more →

What I Mean When I Say That APIs Reduce Everything to a Transaction

My friend Allen Helton asked what I meant when I said, “APIs reduce everything to a transaction” on LinkedIn recently. He was curious whether I meant this conceptually or technically. To be honest, I mean both. I purposely leave it loosely defined, and wield it in many different ways. I do this simply to get people thinking about the nuance of digital transactions we often take for granted. I just want people to ask questions like Allen is doing, and pause from time to time to think about ...

New API to Profile Bookmarklet

I regularly come across APIs that I want to profile as part of my APIs.json “Artisanal” work, but I don’t always have time to actually profile the API with APIs.json and OpenAPI. So I created a bookmarklet that will take the title, description (any text I highlight on page), and URL and submit as new GitHub issue.

Operational API Rules Using APIs.json

I have been immersed in the creation of APIs.json for many of the top APIs out there, including Twilio and Stripe. These APIs are held up as an example for how we should be doing APIs. I wanted to understand this more, so I spent a couple of weeks exploring the APIs.json, and Open...

What Makes Charismatic APIs?

I recently finished reading “How Infrastructure Works”, by Deb Chandra. It is a must read if you are doing APIs at scale today. She opens the book by talking about charismatic infrastructure like the Brooklyn Bridge or the St Louis Arch. These are grand collective public infrastructure projects that rise above, stand out, and have a personality all of their own. This look at physical infr...

I Am Not Sure You Want Me Reviewing Your AI API Startup

I am not sure I am the right person to be asking for feedback on your startup. But, here we go.

API Ecosystem Building Blocks – SMTP, POP, HTTP, CSV, and Stripe

My wife recently moved off of Substack. She was run off by their support of fascism on their platform, and was in real need of supporting her 1,300+ subscribers. I was impressed with her way of handling the research, planning, and ultimate migration of her newsletter operation, and found the pragmatic API story ther...

API Governance is About Limiting Speed

I am all about API governance these days. In my day job, and evening thoughts. I am no longer a cheerleader for all things APIs, unless they serve API governance. As I take all my observations of the universe of APIs over the last thirteen years and scrutinize them through my current lens I am left with a deep awareness that API governance is all about the limitation of speed. I love this title for a blog post because 98% of the people who read it will immediately assume that API governanc...

API Discovery is Hard

Providing useful API discovery solutions is hard. I have dedicated 15 years to understanding and trying to provide solutions to this problem. I regularly gather my thoughts on this subject and invest cycles in moving forward the solutions I feel are needed to help with API discovery. My solutions all revolve around my API discovery format—-APIs.json. As I move from ...

Using Spectral As An API Ratings System

When Steve asked me what we could do with APIs.io, I knew I wanted to improve upon what APIs.io v1 was as an API search, but I also lay the groundwork for what we need to help alleviate our API discovery pain. Every time I have made an investment in API discovery over the last decade, I also find myself considering what constitutes a good API, as well as a bad API, but also effectively dealing with the change that is inevitable across the API landscape. I knew...

APIs.io APIs.json Goodness is Back

Steve Willmott came to me asking what we should do with the APIs.io search engine. I don’t have much interest in developing tooling these days, but I am interested in hardening and moving forward our API discovery format APIs.json. Regardless, to really push forward APIs.json I need to push forward the concept of API discovery, and this is what APIs.io is all about. So, to help me move APIs.json forward I did a round of investme...

The Right Way To Do the API Is Always Negotiated in the Moment

I used to believe there was a right way to do APIs. I don’t anymore. I know better. I’ve seen too many APIs. I’ve seen too many people get frustrated that we didn’t do the API in the right way. Anybody claiming to have the right way is selling you digital moose diarrhea. The right way to do an API is less about the API, and everything about the process, and who you have involved in producing and consuming the APIs. For technologists it is hard to see the process and the people and it is ea...

Seeing Code Execution Differently At The API Gateway

When I published my recent story about where API gateways might be going, I received pushback the most about my inclusion of code execution as a core platform capability. Which I would agree with in our grandfathers or even father’s API gateway realm, but in a gitops, serverless, edge, and programmable API gateway realty, I see things differently. I see a world where the API gateway is part of the fabric of the web. Our father’s API gateway ended up baked into the cloud, but the next gener...

Where Is This API Gateway Thing Going?

According to Gartner, the full lifecycle API management quadrant is going away, but acknowledges in 2023 the API gateway continues to enjoy an outsized amount of focus when it comes to internal and public API operations. The gateway is important, and tends to be where attention is focused in good times and bad, but other stops along the API life cycle are also critical to the conversation as well, and I’m looking to understand more about why, while trying to understand where things might b...

Twilio Makes for a Nice and Clean Example of APIs.json

You really can’t find a better example of APIs.json, then the one for Twilio. Twilio doesn’t have their own official APIs.json (yet), but I created one that I think really shows the strength of the API discovery format. I still have more work to do, but this Twilio APIs.json shows how the format can be used to index an API operation, while revealing individual human and machine readable properties of multiple APIs, as well as a common set of properties across all APIs–this version of my AP...