Where Are All the APIs You Consume?
Why is it so hard to find information about the API operations you use?
Do you know who is supposed to find APIs easily? Developers. Because they're the ones who need to build the integrations. I'm not talking about API discovery, which is something that happens when you're trying to find an API that does something you need. What I'm talking about is the process of finding information about APIs you already know exist. I'm talking about an easy way to get a machine-readable representation of those APIs. An easy way to obtain authorization credentials. A way to get the API SDK. To get everything you need to build integrations. I feel we can do better than what we have done so far. Keep reading if you feel the same way.
This article is brought to you with the help of our supporter: Speakeasy.
Further expanding its best-in-class API tooling, Speakeasy now empowers teams with open standards. The platform simplifies OpenAPI Overlay adoption so you can focus on building. Click the button below to check out the playground.
Every organization with enough people and technology works with APIs. It doesn't matter if it produces APIs. What matters here is that it works with APIs. Someone inside the organization needs to write and maintain code that communicates with APIs. Someone needs to know which APIs the organization is consuming. Someone needs to keep up with the changes that any of those APIs introduce over time. But, how do you find those APIs in the first place?
And, sometimes, teams inside an organization aren't even consuming full APIs. What usually happens is that different teams consume just a few operations from each API. Integrations are often compositions of several functionalities, not the consumption of full APIs. In this context, where do you go to find information about those API operations that your team is consuming?
The so-called "API Portals" are well understood and have reached maturity. However, they're specialized in listing the APIs you produce, not the ones you consume. Code repositories are definitely one way to store information about the APIs you consume. But they're not organized in a way that's easy to search. Having documents that describe your third-party dependencies is fine, but they're not machine-readable. It looks like there's no straightforward solution.
What I'm looking for is an "API catalog." Something that lets you manage your relationship with the vendors behind all the APIs you're consuming. I imagine that you could start by saving the API operations you're using. You'd be able to store things like the path and HTTP method of the API operation, along with any input parameters. You'd also be able to document an example response to help anyone quickly understand how the operation works. With that information, you'd be able to get the required authorization to consume the operation. And, finally, you could also get not a full SDK but just the code for the operation. These, in my opinion, are the very minimum things you need to have a source of truth for the API operations you consume regularly.
There are, however, other nice-to-have features that I'd love to have. One is an easy way to contact the vendor behind each API operation. Imagine you're having an issue and need help. Or, the API is down or responding erratically. Having a simple, direct support channel would be fantastic. Another feature would be the changelog of each API operation. I want to know whenever there's a change in the way I access the operation or in the response. I want to understand if I need to make any changes to any running code and what those changes are. Speaking of code, another interesting feature would be being able to track all the places that depend on each API operation. Here, I imagine having a list of links to a code repository where you could clearly see all the places with requests to each API operation.
With an API catalog like the one I just described, you'd be able to have a centralized location with all the information about the operations you and your team consume. I wonder how most people have been able to consume multiple APIs without having this type of solution.