Here’s a sarcastic version of the provided text:
The Internet Engineering Task Force (IETF) has defined a doozy of a standard for API discovery, promising to revolutionize how APIs are discovered. But what is it, how does it work, and why should the broader API community care?
Today, we’ll be diving into this monumental achievement and exploring its intricate details. API discovery is a daunting task, but api-catalog promises to be a game-changer. This open standard for automated API discovery is designed to collect and organize all available APIs, their versions, endpoints, and links to documentation, all in a single, standardized format. This means that, no matter how intricate your API is, clients or agents will be able to easily discover all the pertinent information in a single API catalog, reducing the burden of scattered documentation and streamlining the discovery process.
One of the key components of api-catalog is the Well-Known URI, which establishes a standard for the format of API location.
The Internet Engineering Task Force (IETF) has defined what might be one of the most promising standards for API discovery so far. RFC 9727, better known as api-catalog, promises to be an open standard for automated API discovery. But what is it, how does it work, and why should the broader API community care?
Today, we’ll dive into this solution and explore how it works in detail. We’ll look at some compelling use cases and consider what the state of API discovery might look like in a few years.
What is api-catalog?
api-catalog is a proposed standard for API publishers to expose a machine-readable catalog of their APIs. This would collect vital information, including names, versions, endpoints, and links to description documentation, and store it in a catalog that can then be used for discovery.
The idea is simple: improve API discovery with a catalog of metadata context, much like you would in a library with a catalog card. In practice, this standard should mean that a client, whether human or machine, should be able to discover all available APIs and methods via a single catalog endpoint, reducing the sprawl of scattered documentation.
How Does It Work?
api-catalog works by formalizing a few main components. While the RFC is pretty clear that some aspects are flexible — notably the URI path is not mandated as stated in the RFC — it’s expected that those adopting this standard follow some core component structures.
Well-Known URI
RFC 9727 specifies that the api-catalog should be located at a URI that aligns with the standard set by the Well-Known specification defined under RFC 8615. In practice, this should look something like this:
https://example.com/.well-known/api-catalog
How this resolves and in what manner is left up to the publisher. The RFC notes the following as valid as long as the ultimate flow is to the catalog in question:
https://www.example.com/my_api_catalog.json can be requested directly or via a request to https://www.example.com/.well-known/api-catalog, which the Publisher will resolve to https://www.example.com/my_api_catalog.
This URI will act as the entry point into the catalog via the link relation.
Link Relation
The link relation piece of this again calls on another proposed standard, RFC 8288. This format will allow publishers to define their catalog location and provide some basic metadata even if the client or agent isn’t aware of where the catalog itself lives. The following is an example format from the RFC that points to an API catalog .json file:
HTTP/1.1 200 OK
Content-Type: text/html; charset=UTF-8
Location: /index.html
Link: </my_api_catalog.json>; rel=api-catalog
Content-Length: 356
<!DOCTYPE HTML>
<html>
<head>
<title>Welcome to Example Publisher</title>
</head>
<body>
<p>
<a href="my_api_catalog.json" rel="api-catalog">
Example Publisher's APIs
</a>
</p>
<p>(remainder of content)</p>
</body>
</html>
The Linkset Catalog
Now we get to the meat and potatoes of this proposal — the actual linkset catalog. The .json file my_api_catalog.json could look something like this:
{
"linkset": [
{
"href": "https://api.example.com/v1/",
"rel": ["item"],
"title": "Core API",
"type": "application/json"
},
{
"href": "https://api.example.com/v1/openapi.yaml",
"rel": ["service-desc"],
"type": "application/vnd.oai.openapi+yaml"
},
{
"href": "https://docs.example.com/api/v1/getting-started.html",
"rel": ["service-doc"],
"type": "text/html"
},
{
"href": "https://api.example.com/payments/v2/",
"rel": ["item"],
"title": "Payments API",
"type": "application/json"
},
{
"href": "https://api.example.com/payments/v2/openapi.json",
"rel": ["service-desc"],
"type": "application/vnd.oai.openapi+json"
},
{
"href": "https://docs.example.com/payments/v2/index.html",
"rel": ["service-doc"],
"type": "text/html"
}
]
}
You’ll notice that throughout this catalog, we define a few metadata pieces. Firstly, we define the href where the API lives, then state the relational link. This allows us to define what the element type is — for instance, noting that something is an item, or a service description.
Note that this is different from the relational link we noted earlier. That relational link only pertains to the location of the api-catalog, whereas the linkset link relational link notes what kind of relation the element has to the API. This allows developer tools, agents, or even AI models to retrieve a structured list of all available APIs with their documentation links.
Why Does This Matter?
So why this RFC, and why now? APIs are much more ubiquitous than they were even ten years ago. With so many services on offer, often composed of many smaller services and APIs, the need to make APIs discoverable has only increased. There are a few key reasons for this to be the case.
Firstly, the process of API discovery was historically a very manual process, which relied heavily on developer portals, documentation, and other materials. For machines, this was always a subpar experience, but now that AI agents have become more and more commonplace, what was once a caveat is now a huge blocker. By providing a standardized methodology for machine-readable discovery, api-catalog intends to solve this issue and make agentic systems better.
Secondly, governance and security are growing ever more important. The need to understand where data is coming from, where it’s stored, how systems interact with it, and where the APIs in an organization live is now critical in 2025. As such, having a single source of truth for API discovery has a significant effect. Everything from identifying shadow APIs to improving version management can stem from this innovation.
Finally, API discovery as an engine for removing guesswork is critical, especially in this new agentic reality. Outside of just being able to discover APIs, systems might need to have better context on how these systems interact and function in context with one another, and this provides that in ample supply.
Who Is This For?
api-catalog is an interesting solution, but it doesn’t mean your average developer will use it to define API catalogs by hand. Instead, we are more likely to see API management platforms taking on this standard as a methodology for auto-generating schema-driven catalogs.
Providers such as Kong, Apigee, or AWS Gateway will likely find significant value in a pre-determined format standardized throughout multiple API systems, allowing for generation based on the observed environment. This will cut down significantly on the vendor-specific implementations if broadly adopted, and could pave the way to a universal API consumption and discovery model.
Of course, that is the core challenge of this solution: if broadly adopted. Right now, this RFC is entirely experimental, and we’ll need to see wider adoption to see if the RFC stands the test of time. If API gateways, portals, and developer tooling broadly integrate this standard, api-catalog could drive a renaissance of API discovery and consumption akin to what RSS did for blogs and websites, almost like a robots.txt for APIs. If it’s not widely adopted, the underlying discovery problem will persist, and new standards will likely be needed.
Time Will Tell For api-catalog
RFC 9727’s api-catalog is a forward-looking standard that could reshape how APIs are discovered and consumed, especially in a world where machine-to-machine and AI-driven integrations dominate. While adoption is still early, the concept aligns perfectly with the needs of modern ecosystems, where automation, clarity, and discoverability are key.
What remains to be seen is if larger, broad adoption is actually going to happen, or whether this is another standard in a sea of standards vying for adoption and awareness.
