Blog

I am perpetually fascinated by house people “see” APIs based upon their role, experience, and how they are incentivized to work on APIs. For the last decade plus, my strongest way of assessing where some is located in the API realm and how they “see” APIs, is the OpenAPI specification. This open-source JSON or YAML specification for defining the surface area of an API has become the best way to understand if you and someone else you encounter on your API journey are on the same page, and p...

I have been exploring the addition of a new property type to APIs.json called “Contract”. I wrote about recently how we need to expand our definition of the API contract beyond a technical contract like OpenAPI or AsyncAPI. I am looking to establish a baseline any company could use as a boilerplate contract bet...

I have found thirteen more solid examples of API providers using GitHub to manage their OpenAPI and related artifacts. I am regularly finding these as I am profiling APIs, and rather than just write a blog post each time I figured I’d store as YAML, and keep adding them in batches every couple of weeks.

I hear this frequently about my APIs.json work-—it needs to scale. People struggle with understanding why I would hand-craft an APIs.json search index for other peoples APIs. Trust me, I sure wish they would. My work only happens so fast. But, at least the work still gets done, and I learn a lot along the way, while simultaneously hardening the surface area of APIs.json. Plus, I enjoy doing it. I find it relaxing to come home after a full day’s work, discover new APIs, and hand-craft index...

I am working on producing an APIs.json for the Train Travel API produced by Bump.sh. I am adding the API to the API Commons as a base API, and publishing an APIs.json is where it all starts. I will be producing a template type APIs.json for the API, and will leave for Bump.sh to create an index of their own API. I am simply looking to build on their great work and establi...

It was interesting to approach API search and discovery with a blank slate. When we got APis.io back, both APIs.json and API Commons were fairly dormant, and adoption has been minimal. Partly due to our collective lack of investment, but also due to the state of the API space. It isn’t just APIs.io—ProgrammableWeb is gone. Real or perceived, there just doesn’t appear to be any money in API search and discovery, or at least not the kind of money that investors are interested in. Collectivel...

In recent years we’ve begun collectively using the phrase “API contract” to often describe the OpenAPI or AsyncAPI for our APIs. While I have been complicit in the adoption of this phrase, and support its usage anytime I can, I also feel that it also reflects much of what is deficient with the API Economy. I agree that an OpenAPI represents a contract between producer and consumer, but I am painfully aware of how this represents just the technical side of this contract, and much of the bus...

I wrote about Stripe and Twilio not using PUT for updates a couple months back. Since then a co-worker happened to have the chance to sit next to the CTO of Stripe at an event, and was able to ask them directly why they made the decision to use POST for both creating and updating their resources. The answer was simple, their customers utilized integration solutions that couldn’t s...

While writing the story on Bump.sh’s adoption of APIs.json I stumbled across their story on replacing the ubiquitous PetStore OpenAPI that comes default with the Swagger and OpenAPI tooling of the previous decade. I am a big fan of replacing this default OpenAPI that comes with services and tooling, but I am als...

There are many ways your public API can be deficient. It is these areas I am mapping with APIs.json and looking to standardize with API Commons. The common building blocks of public API operations represent the visible behavior (or lack of) of API producers, but also reflect the behavior (or lack of) API consumers. There is a lot to read in these tea leaves if you take the time. While public APIs are just the tip of API iceberg, everything you need to know about a company can be read in th...

Many of us pundits, analysts, and even practitioners in the API space believe in doing APIs the right way, or at least giving them the attention they deserve. This is commendable, but also the minority view of how you do APIs. Us technologists consciously and subconsciously ignore the business realities that exist on the ground for my API producers when we assume that everyone is interested in doing APIs well, and maximize the usage and adoption of their API. When you have looked at as man...

I was pleased to see the good folks over at Bump.sh have adopted APIs.json as the discovery format for their API documentation hubs. They have a nice write-up on how to Make your APIs Discoverable with APIs.json, walking through how APIs.json works and how it is automatically generated as part of your API documentation hub. The article is written ...

I am always fascinated by the dogma that exists around each successful API pattern that comes along. Everyone believes their “aha” moment is elevated over everyone else’s “aha” moment. I’ve been guilty of the same response many times over the years. It takes practice and time to be able to elevate yourself over the dogma and see the value and benefit of any individual API pattern, and even then you’ll still be subject to being sucked back down with new trends, and peer pressure along the j...

I’ve learned a lot performing as the API Evangelist over the years. The landscape never fails me when it comes to revealing new lessons, and last year switching from Postman, an API service provider, to Bloomberg, an API producer has been no exception. I’ve been extremely frugal in the conversations I have had during this switch, relying mostly on Zoom and LInkedIn conversations to engage with folks across the API space. These ongoing conversations, while also continuing to lightly stay in...

I have a custom built set of admin tools for APIs.io that help me quickly build APIs.json and OpenAPI indexes for search. While I am a believer in using AI, I am a skeptic of all the hype going on around AI right now. Well trained ML models developed on high quality sources of data and content have the potential to do many useful things. However, I know all too well that when you have garbage into your API models you get garbage out. So, amidst all of this hustle and hype I enjoy having r...

My time at Postman came to such an abrupt end I haven’t had time to properly assess all the work I did during my time there. I just had brunch with my partner in crime LeTroy Gardner and his partner Joy, and a flood of memories have come to the surface. To help me work through I wanted to write about my time creating and producing almost 150 overall episodes of the Breaking Changes podcast I did while working at Postman. I am very proud of what I did...

It takes time to properly craft an APIs.json for an API provider. It is something I wish API providers would do on their own, but in an effort to help jump start this I am profiling many of the top API providers. I’ve been working on Amazon Web Services (AWS) for a while now, but finally got the core AWS APIs.json index, but more importantly the [APIs.io...

I am working to better define and shape when and how I apply both JSON Schema and Spectral rules. Both specifications are invaluable when it comes to API governance, and have significant overlap, but there are many ways in which they differ when it comes to trying to define, shape, and ultimately govern the API landscape. I don’t pretend to have the answers here, but I know enough to know these are complex technological specifications seeking to tame a sprawling API landscape, and I enjoy ...

I have a lot of work to do profiling APIs using APIs.json. I am interested in producing as complete an accurate APIs.json for an API provider as I possibly can. When it comes to profiling providers like Amazon Web Services (AWS), this means there are over 350 individual APIs. It isn’t enough that I have a name, description, and tags for each API, but I also want OpenAPI and other propertie...

As I begin to work on renewing one of my existing API projects, I wanted to sit back for an afternoon and assess where things are. I see APIs everywhere. I see them on my work to work powering my city’s transit system all the way to the badge I swipe when I enter the building for work. I see APIs as I message with my wife, get my news, and make a reservation for dinner this evening. APIs are ubiquitous while also being incredibly invisible. APIs touch every part of our daily lives, but mos...

While interviewing over a hundred people on my Breaking Changes podcast, the lack of alignment between business and technical groups while delivering and iterating upon APIs was the number one source of friction across enterprise organizations. While API governance is an essential aspect of it, ensuring that your API program speaks to business people as well as developers like ...

I hit a ceiling with my Artisanal APIs.json API profiling, in that I am pushing over a thousand individual APIs. It reminds me of running conferences, and once you get over 500 people, everything begins to change. I only have a little over 100 API providers, but when some API providers have 100+ individual APIs, it adds up very quickly. When you are working to properly profile APIs using OpenAPI and the operations around them with APIs.j...

Since the beginning of the specification, APIs.json has had an “apis” property as well as an “includes” properties, providing a way to immediately index your APIs, or “include” a reference to other APIs.json indexes. The APIs.json specification is designed to be flexible in how you can define and organize your collections, but as I spend more time profiling and indexing APIs, I am finding a need to further expand on how APIs.json indexes work together in...

I have long stated that I am focused on in the intersection of the technology, business, and politics of APIs with my storytelling. When I started API Evangelist I was fairly well versed in the technology of APIs, but I wanted to learn more about the business of APIs. I knew there was more to what I was seeing than just the technical aspects of doing APIs, so I sat down to learn. After a couple of years I realized that politics of APIs were another critical piece of the pie, leaving me stu...

I am like that kid in the Sixth Sense movies. But instead of dead people I just see APIs. When I see you, I don’t see a person. I see a bunch of API calls. To me, you are just the sum of all of the API calls you make in a day. Honestly, I don’t even care about all of the transactions you make in a day-—you only matter as part of a larger demographic aggregate of API calls that speak to where I think there is opportunity for growth. You are just part of a larger suite of derivative financia...