Alternative Ways to Make Your APIs Discoverable
Make consumers happier by making it easier to find and use your APIs.
A few days ago, I noticed that it's been ten years since I did a presentation titled "How to Automate API Discovery." Back then, I thought that API discovery hadn't been fully automated because some parts of it were expensive. I suggested we should focus on code generation, integration automation, and consumer provisioning, as the market offered viable solutions. Search and documentation, however, had a higher cost of automation with no evident benefits. What has happened since 2015, and where are we today with respect to API discovery? Follow me and let's find out.
This article is brought to you with the help of our supporter, Scalar.
Scalar is a suite of powerful & customizable developer tools to help you at all stages of API development. Create beautiful API Documentation in a notion-like editing experience.
One way to make discovery easy is to make consumers and producers agree on a format and protocol for communicating details about available APIs. As long as an API producer publishes a document in a location the consumer finds convenient, discovery can happen. The document must contain enough information to understand where to find the APIs and how to consume them. Since 2015, different people have attempted to solve the problem of API discovery. However, it seems there hasn't been enough traction on any of the proposed solutions to reach success. Let's look at each of those iterations, starting with APIs.json.
Sometime in early 2014, Kin Lane and Steven Willmott began drafting a document titled "API Discovery Format." Lane was, at the time, an API evangelist working closely with Willmott, who was the co-founder and CEO of 3scale, one of the first API management companies in the market. Lane wrote about the process of launching APIs.json in August 2014. "I think we got the feedback from the community we needed to get to the first stable version," Lane wrote, referring, I presume, to version 0.14 of the specification. Since then, it's evolved up to version 0.18, which was published in May 2024. According to the official documentation, it's "a machine
-readable specification that API providers can use to describe their API operations, similar to how websites are described using sitemap.xml." The focus here is on how comprehensive the specification can be. The format supports almost 30 types of properties, including things like authentication, license information, pricing, and documentation. The specification also defines that the apis.json document must be at the root level, e.g., https://example.com/apis.json. Additionally, you can have it in several formats such as markdown, plain text, and, obviously, JSON. Overall, APIs.json looks like an interesting solution to the API discovery challenge. Or, at least, one part of the solution, because it doesn't offer any mechanism for searching for APIs.
A large part of discovering an API has to do with search. That's probably what made Mike Amundsen publish the "Discovering Interoperative Services for Continuous Operation" (DISCO) specification in September 2019. Amundsen is a well-known author and consultant in the API space. Even though the author of DISCO considered it a proof-of-concept, it's worth mentioning and analyzing here. The specification describes an API registry that you can use to register and unregister services, find the service you're interested in, advertise your intention to use a service, and even prove that a service is up and running. This last operation can be replaced by a health-check endpoint if you have one. In essence, DISCO offers at a low level what you'd expect on an API portal, but to be consumed programmatically. Compared to APIs.json, it offered more features at the operational level. Which leads us to the latest alternative, which goes back to a more theoretical approach.
RFC 9727 offers what I consider the best of both worlds. Its approach is similar to that of APIs.json in the sense that it defines the location and format of a machine-readable API discovery document. However, what it provides is an operational way of indexing and then potentially finding the APIs you're interested in. Kevin Smith, a distinguished engineer at Vodafone, proposed the specification as an IETF draft in 2023 and has been working since then to make sure it turns into an RFC. It takes advantage of the /.well-known path to represent the location of the API catalog document. Or, you can simply use a Location header to indicate where your API catalog is located. Inside an API catalog document, you can add as much information as you like. You can be as thorough as you'd be with an APIs.json document, or you can simply point to an OpenAPI description. What's important here is that the document follows the linkset format, which lets you add links to documents that define attributes of each API. This approach makes it easy for any search system to index the information defined for each API.
So, where are we today? After more than ten years since the launch of APIs.json, we're at a point where there's no discovery solution available in the market. RFC 9727 looks like our best bet, but it doesn't offer the search features that DISCO wanted to provide. The next steps are what I call market validation, which involves one or more vendors attempting to commercialize what RFC 9727 defines. Would you use such a product?