Automating API Discovery with RFC 9727
Is this the best way to programmatically advertise your APIs?
If API discovery is hard for a human, imagine what a machine would feel when searching for an API. And, by a machine, I don't necessarily mean anything with intelligence. What I see is that it's practically impossible to programmatically find and use the APIs you're interested in. Unless, of course, there was a machine-readable way of advertising their locations. Well, it turns out there is. Keep reading to learn all about it.
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.
It all started with a draft in May 2023. Since then, Kevin Smith, a distinguished engineer at Vodafone, has been iterating on what became a proposed standard in June 2025. It took Smith 13 revisions, two years, and an immeasurable amount of passion to get from a first idea to RFC 9727. So, what is inside this RFC that is so important to us? Nothing less than the definition of a way to programmatically find the location of the APIs of a publisher. The author calls this mechanism an "api-catalog."
According to the RFC author, "a request to the api-catalog resource will return a document providing information about, and links to, the Publisher's APIs." In essence, the api-catalog is a document that holds all the information you'd need to consume any of the existing APIs. So, how would you programmatically find the api-catalog resource? This is one of the things the RFC covers.
Smith, the author of the api-catalog, takes advantage of RFC 8615 to define how someone would know where the api-catalog resource is located. RFC 8615 presents the concept of "well-known" URIs and opens the door to many "automatic discovery" mechanisms to take place. What it says is that there's a path called /.well-known that you can use to share resources publicly. In principle, it looks like a simple proposal, but it guarantees that there's a place that both publishers and consumers can use to share the resources they care about. Which is exactly the proposal for the api-catalog resource. It says that any consumer can programmatically find information about existing apis on the /.well-known/api-catalog URI. This is just one piece of the puzzle. But what happens when you're the publisher and you want to use a different path? The RFC also proposes a way to make that work.
There's a technique in HTML called "link relations" that you can use to identify the meaning of any link. Common examples are the links to the previous and next pages on a list of results. By adding the "previous" and "next" link relations, consumers of the page, e.g., Web browsers, can programmatically understand what those links mean and render them accordingly. What Smith proposes in RFC 9727 is the "api-catalog" link relation. So, basically, whenever you add a rel="api-catalog" attribute to a link on an HTML document, you're signaling that the link points to an api-catalog resource.
A similar way to do that, but at a protocol level, is to add a link relation as an HTTP header. The effect is the same as with the rel tag, but consumers don't need to interpret the HTML before accessing the link relation. You can do it by adding an HTTP Link header with the following format: </example.json>; rel=api-catalog. Replace "/example.json" with the path to your api-catalog document, and you're done. In summary, you can announce where consumers can discover your APIs by creating a /.well-known/api-catalog resource, by adding a link relation HTML tag, or by creating an HTTP Link header. What about the contents of the api-catalog document? Let's cover that now.
The contents of an api-catalog document must follow the Linkset format. This is a format that the RFC 9264 describes as a representation of "sets of Web links and their attributes." The format has the application/linkset+json media type with the profile parameter value of https://www.rfc-editor.org/info/rfc9727. In its simplest form, the document is just a JSON list of links inside a linkset object. However, you can add more data, such as version information, and links to the OpenAPI description documents of each API. Here's an example with one single API that enriches the catalog with the description and documentation links:
{
"linkset": [
{
anchor: "https://developer.example.com/apis/ex01",
"service-desc": {
"href": "https://developer.example.com/apis/ex01/openapi.yaml",
"type": "application/yaml"
},
"service-doc": {
"href": "https://developer.example.com/apis/ex01/docs",
"type": "text/html"
}
}
]
}Appendix A of RFC 9727 lists more examples, some of them quite simple. Something that caught my attention is that the format of the api-catalog document is too loose. In other words, you're free to list your APIs in different ways as long as you put them inside a JSON array called linkset. At first, this feels great because it gives you, the API publisher, the freedom to pick which format works best. However, it makes it harder for consumers to discover your APIs because they don't know which format you picked. That can be easily solved if the api-catalog document always follows the same format.
In summary, RFC 9727 offers a robust way to allow programmable API discovery at scale. The versatility of how the api-catalog works lets publishers with different needs and resources easily publish their APIs. Discoverability is easy to reach by consumers as long as they follow the instructions on the RFC. Now it's just a matter of time until API portal vendors embed the api-catalog solution into their products.