API-catalogusgenerator
Vermeld je openbare API's één keer en genereer de JSON-linkset die RFC 9727 voorschrijft voor /.well-known/api-catalog, plus een nginx-blok dat het bestand met het juiste mediatype serveert.
{
"linkset": [
{
"anchor": "https://api.example.com/v1",
"service-desc": [
{
"href": "https://api.example.com/v1/openapi.json",
"type": "application/openapi+json"
}
],
"service-doc": [
{
"href": "https://example.com/docs/api",
"type": "text/html"
}
],
"status": [
{
"href": "https://status.example.com"
}
]
}
]
}
location = /.well-known/api-catalog {
default_type application/linkset+json;
add_header Link '</.well-known/api-catalog>; rel="api-catalog"';
try_files /.well-known/api-catalog =404;
}
Upload het bestand naar /.well-known/api-catalog en serveer het als application/linkset+json. Het nginx-blok stelt dit mediatype in en voegt een Link-header met rel="api-catalog" toe, zoals RFC 9727 voorschrijft voor HEAD-verzoeken.
Waarom een API-catalogus publiceren
Een agent moet je API eerst kunnen vinden voordat die deze kan aanroepen. RFC 9727, gepubliceerd in juni 2025, biedt daarvoor een vast startpunt: de well-known-URL /.well-known/api-catalog en de api-catalog-linkrelatie waarmee elke pagina ernaar kan verwijzen.
De catalogus is een linkset in JSON. Elke vermelding is gekoppeld aan de basis-URL van een API en verwijst naar de machineleesbare beschrijving (service-desc, meestal een OpenAPI-bestand), de documentatie voor mensen (service-doc) en de statuspagina. Een client leest één klein bestand in plaats van je documentatie te crawlen.
Volgens de RFC moet het antwoord application/linkset+json gebruiken en hoort het het profiel https://www.rfc-editor.org/info/rfc9727 te bevatten. We weten nog niet welke agents het bestand opvragen, maar het is slechts één statisch bestand dat je hoeft te publiceren.
Vragen over api-catalog
Wat is /.well-known/api-catalog?
Dit is de locatie die RFC 9727 definieert voor een machineleesbare lijst van de API's van een organisatie. Het bestand is een JSON-linkset die elke API koppelt aan de beschrijving, documentatie en statuspagina. Clients kunnen het bestand daar rechtstreeks vinden of via de api-catalog-linkrelatie.
Welke Content-Type heeft api-catalog nodig?
Volgens RFC 9727 moet dit application/linkset+json zijn en hoort de profielparameter https://www.rfc-editor.org/info/rfc9727 erbij. Het nginx-blok op deze pagina stelt het mediatype en de Link-header in. Voeg de profielparameter zelf toe als je serverconfiguratie dat ondersteunt.
Heb ik een OpenAPI-bestand nodig om een catalogus te publiceren?
Nee. In deze generator heeft elke vermelding alleen de basis-URL van de API nodig; links naar de beschrijving, documentatie en statuspagina zijn optioneel. Met een OpenAPI-specificatie kan een client je endpoints ontdekken zonder documentatie te hoeven lezen. Voeg er dus een toe als je die hebt.
Wat is het verschil tussen api-catalog en llms.txt?
api-catalog is een RFC van de IETF die API's als JSON-links vermeldt voor software die ze aanroept. llms.txt is een voorstel voor een Markdown-index van pagina's, bedoeld voor taalmodellen die documentatie lezen. Ze overlappen elkaar niet, dus je kunt beide publiceren.