Alternative Use Cases for API Discovery
Unlock API Discovery use cases relevant to support, consumption, and creation.
API Discovery is a combination of pure luck and word-of-mouth. This is how I felt when I first wrote about API Discovery in 2016. Back then, machine-readable API definitions weren't as ubiquitous as they are now. Putting together a system for easily finding an API wasn't as easy as it is today.
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.
Now, it's possible to put together a searchable index of a list of API definitions. APIs.io is a great example of an API search engine. You can do a free text search to obtain a list of APIs that match your criteria. Each API entry lets you access common attributes such as documentation, pricing, and machine-readable definitions.
This is what I see as a top-down search pattern. You start with an idea of the kind of API you're looking for. You then browse the search results until you find what you're looking for. This use case is interesting because it lets you discover new APIs. However, other use cases can provide more immediate value, even when you're not searching for an API.
Finding the team behind an API operation
Did you ever find yourself in a situation where you knew the URL for an API operation and you needed to get in touch with the team behind it? Well, I remember a few times when that happened to me and it wasn't easy to find who was maintaining the API operation.
Unfortunately for many, this scenario happens quite often. Especially with people who do technical support. When customers complain that something isn't working as it should they want a quick response usually followed by an investigation and a fix. Obtaining the name of the team that can help with a fix would be ideal.
Here's a simplified user story that can describe this API Discovery scenario:
As a Technical Support Engineer,
When I receive a support request,
I want to find out the team responsible for the API operation,
So that I can obtain a fix.
The input to this search can be a full URL of the API operation or just the name of the operation. What matters is the nature of the discovery. The support engineer wants to find out what team can help remediate the issue customers are reporting. The result of the search has to be the team's contact information.
This use case is relevant while doing API support or troubleshooting. Let's now look at a use case that offers value while consuming an API.
Generating client code for an API operation
Obtaining a full SDK for an API is a given nowadays. Whether the API provider offers it or you generate it yourself, you know it's possible to have a full SDK without much effort. While having a full SDK is interesting, what could be even more relevant is obtaining just the code you need to consume an individual API operation.
Imagine being inside your favorite code editor and, after typing the URL of an API operation, getting the full code to consume it. The code should include a way to connect to the API, authentication parameters, and any payload object required by the operation. All you have to do is fill in the blanks and execute the code.
Here's the user story for this API Discovery scenario:
As a Software Developer,
When I write code using my favorite editor,
I want to obtain consumer code for an individual API operation,
So that I can integrate it with my application.
To obtain the generated code you could simply input the full URL of the API operation or you could interact through a chat UI and request the code for the operation. The second option is currently available, at least through GitHub Copilot (see recorded screencast).
This recorded screencast shows GitHub Copilot Chat generating consumer code to interact with Adafruit's API "All dashboards operation". This is an API operation I chose randomly to illustrate how code generation works.
The value of this use case lies in its ability to aid during API consumption. The next use case, however, is relevant during API creation.
Auto-completing schema information
When you're creating API you'll most certainly end up having to decide what data types you'll use. Being able to consult existing data schemas to avoid duplicating efforts is highly valuable. One of the goals of API Design is to promote consistency across an organization's APIs. And reusing data schemas is a sure way of being consistent.
In this use case, you're an API Designer working on your favorite tool. By simply typing the URL of an API you'd be able to list all its schemas. To do an autocomplete of a schema you'd type the schema URI and your tool would translate that into the full schema in place. Or, you could type the absolute URI of a schema, if you already know it.
This is a possible user story for this API Discovery use case:
As an API Designer,
When I create an API definition using my favorite tool,
I want to obtain a schema of an existing API,
So that I can reuse it and promote consistency.
Conclusion
These are examples of API Discovery use cases that don't follow the typical top-down pattern I described earlier. Instead of searching for an API by one of its identifiers (title, description, tags, etc.), you want to find relevant information related to it. In the first use case, you already know the API operation URL and you want to find the team that maintains it. The second use case lets you generate code to consume an API operation that you already know about. Finally, with the third use case, you're able to reuse schemas from existing APIs.
I believe all three use cases can be easily available today. The second one is surely available through GitHub Copilot Chat as I show on a recorded screencast. The other two can also be used or implemented using existing technology. The ability to make these use cases relevant isn't related to technology, though. The more information about your APIs you make available in a machine-readable format, the more use cases you'll be able to unleash.