Completing our digital supply chain and factory floor API analogy, the last legs are the wholesale and retail distribution channels. Your API developer portal(s) are your wholesale distribution channels, but it is important not to forget about the applications you develop representing your retail distribution channels. The raw resources (internal APIs) and resources and capabilities from suppliers (3rd-party cloud and on-premise APIs) are combined with your products (3rd-party and 1st-part...
API conversations are hard. Not because APIs are hard, but because they are virtual and difficult to see, and there are multiple perspectives and scopes existing across individual APIs, and the APIs that exist across an enterprise, as well as the industries they operate in. One of the most interesting aspects of doing APIs I have witnessed in the last 15 years of API hustling, is that it is very easy to talk past each other, with one person focused at one level and the other at another lev...
I wanted to take a moment to once again develop my understanding of why OpenAPI was successful. Some would argue that its success is unevenly distributed because of Swagger-—which is true. I would also say it is also unevenly distributed because of Postman collections, GraphQL, and now with the latest release of AsyncAPI, which enables you to define request/response APIs, this will continue to expand. Even with all of this, it is difficult to argue that OpenAPI is the de facto machine-read...
One way I keep my finger on the pulse of API governance is studying the job postings out there in any given moment. I learn a lot from what companies are asking for via their job posts, while also understanding which companies and industries are finding themselves at the point in their API journey where API governance is needed.
I am always fascinated by how us technologists can’t leave our backends out of API discussions. Keeping an API design conversation just about the interface between a producer and consumers proves to be one of the most difficult things about collaborating within or across teams. Sure, there are plenty of backend concerns expressed in interfaces, but those things need to be abstracted away and distilled down into only what is needed for a single, or series of API transactions with consumers....
HTTP Web APIs are the dominant form of private and public APIs. It has been this way for over a decade, and will continue for some time to come. I know that GraphQL, gRPC, Kafka, and other API believers feel confident they will displace their simpler HTTP variant, but I am fairly confident they won’t when it comes to externally available 1st and 3rd-party APIs. HTTP Web APIs, or often called REST, RESTful, or RESTish dominate because they are simple (most of the time), cheap, and messy—-ju...
I have really, really, really missed the public conversations I was having on my Breaking Changes podcast, as well as the private conversations I’ve been having with enterprise folks across different business industries as the Chief Evangelist at Postman, and as the API Evangelist–these conversations are the feedback loop for my storytelling and the nutrients required for my soul.
I have been studying the GitHub repositories of API producers who choose to manage their OpenAPIs via a public repository. I have broken down all the properties of these repositories to help me better understand how producers are managing their OpenAPI, but also how they perceive or their consumers are requesting different things derived from and surrounding a valid OpenAPI definition f...
My friend Emmanuel Paraskakis recently published a list the top 7 Ways To Screw Up Your API Product-—which I agree with, but told him I’d ponder and add some of my to the list. From Emmanuel’s experience, here are the top ways we cause ourselves API pain when it comes to enterprise operations.
I was stuck in a cycle of thinking yesterday about the executability of an OpenAPI vs. Postman Collection. I am closely watching the Arrazzo spec for defining workflows, but I am very interested in the executability of an individual API operation using an OpenAPI. I was stuck in a rut thinking that my collection is ...
I hear a lot of complaints from developers about the usage of YAML when it comes to defining APIs. I have a pretty strong design and develop time YAML, and build and run time JSON philosophy in my work. I use YAML to define, configure, and validate EVERYTHING until it reaches a state where it is building, deploying, and operating as part of runtime—-then it is all JSON. I do this as a concession for business stakeholders, to help them get more involved in the design and development of APIs...
It is loud down here amongst the APIs. It is hard to hear your own voice over the noise, and after you have many folks tell you that you can’t speak, or heavily edit you when you do speak, you begin to forget what you sounded like back when you had your voice. Your leadership, your coworkers, your partners, your investors, and the industry are all telling you what you should and what you shouldn’t be talking about. It is easy to be quiet, do what you are told, and get lost among the nutrie...
Friday was my last day at Bloomberg. I learned what I had come there to learn and now it is time for me to get back to my API Evangelist work. Moving forward, I will be taking my previous API Evangelist foundation, combining it with what I learned at F5 and Bloomberg (both enterprises), but also what I learned at Postman (a startup) through my conversations with numerous enterprise customers, as well as via my 125+ Breaking Changes podcast episodes, then applying it all as a new podcast (k...
I am perpetually fascinated by how 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 pre...
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 ...
