Where Is My OpenAPI?
Where Is My OpenAPI?
OpenAPI could make consuming APIs so much easier if definition documents were easily accessible.
Why can't I easily find the OpenAPI definition document for most of the APIs I want to consume? I mean, OpenAPI has been around for 14 years. And yet, many companies still aren't using it to promote their APIs publicly. While some popular APIs have their OpenAPI documents public, they're not easy to find from their documentation.
This article is brought to you with the help of our supporter: Speakeasy.
Speakeasy provides you with the tools to craft truly developer-friendly integration experiences for your APIs: idiomatic, strongly typed, lightweight & customizable SDKs in 8+ languages, Terraform providers & always-in-sync docs. Increase API user adoption with friction-free integrations.
OpenAPI as a description language has the benefit of providing a common language that different stakeholders understand. With the help of open-source and commercial tools, this common way of defining APIs improves areas such as testing, documentation, deployment, and observability.
All this is nice and beautiful when you're thinking about using OpenAPI internally. But, what if you're trying to access it as an external API consumer? From an API consumer perspective, automating everything related to building and maintaining integrations has obvious advantages. If you're not making your OpenAPI definition available you're not offering all those advantages to consumers.
The title of this article came to me after reading "Where Is My Flying Car?" This book by J. Storrs Hall shows how sometimes the best available technology doesn't enhance people's lives as expected. You can't buy a flying car today and use it on your daily commute. Even though the technology to make it happen is, in theory available, somehow the market dynamics didn't play in that direction. Something similar is happening with APIs, as I see it. Even though OpenAPI is available you can't easily use it to consume your favorite API.
Let's look at a few examples of popular APIs to learn how you can find their OpenAPI definition documents. The first example is the API that most people refer to when thinking about good practices. When you open Stripe's API reference you can find a very comprehensive and user-friendly documentation. However, finding the OpenAPI definition is an almost impossible task. To find it you have to open the "Developer tools" documentation, then "SDKs Overview," and finally click on "Stripe OpenAPI Specification." The OpenAPI is there but it's not directly accessible from the API reference as I think it should. In fact, it's a link to a GitHub repo that contains the OpenAPI document.
The second API I want to analyze is OpenAI's. After you open their API reference, try finding the OpenAPI definition document. After a few tries I could find it referenced on the Changelog page. Guess what? It's a link to a GitHub repo where the OpenAPI definition document is located. They seem to be using the repo primarily to re-generate their SDKs every time the OpenAPI definition changes.
Other APIs follow a similar pattern or, even worse, they don't provide an OpenAPI document at all. PayPal and Sendgrid have their OpenAPI on a GitHub repo, many of Google's REST APIs don't offer an OpenAPI at all, and I couldn't find AWS's OpenAPI definitions. Altogether, if it weren't for the effort of the community, you couldn't find any OpenAPI documents. Projects like APIs.guru and APIs.io have been offering a simple way to discover all those OpenAPI documents that are hard to find. And, many times, the people behind those projects end up creating OpenAPI definitions for the APIs that don't have one.
I feel there's a misalignment somewhere preventing API producers from investing in their OpenAPI definition documents. Or, it could be that producers feel they'd lose control if they opened their machine-readable definitions to the world. In an ideal world, I'd want to use any OpenAPI document, render documentation, and generate code to integrate with the API. I don't see it any simpler than that.
Fortunately, there are examples of approaches that give OpenAPI its much-deserved spotlight. Whenever I open an API documentation the first thing I look for is a link to its OpenAPI definition. Start paying attention—if you haven't already—and you'll start noticing some documentation tools following the good practice of promoting OpenAPI. While we don't have flying cars yet, I wish, as a consumer, we could all have our OpenAPIs easily accessible.