API-Kataloggenerator
Listen Sie Ihre öffentlichen APIs einmal auf und erhalten Sie das JSON-Linkset, das RFC 9727 unter /.well-known/api-catalog erwartet, sowie einen nginx-Block, der es mit dem richtigen Medientyp bereitstellt.
{
"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;
}
Laden Sie die Datei unter /.well-known/api-catalog hoch und stellen Sie sie als application/linkset+json bereit. Der nginx-Block setzt diesen Medientyp und fügt einen Link-Header mit rel="api-catalog" hinzu, wie RFC 9727 es für HEAD-Anfragen erwartet.
Warum einen API-Katalog veröffentlichen?
Ein Agent, der Ihre API aufrufen möchte, muss sie zunächst finden. RFC 9727, veröffentlicht im Juni 2025, legt dafür einen festen Einstiegspunkt fest: die Well-Known-URL /.well-known/api-catalog sowie die Link-Relation api-catalog, mit der jede Seite darauf verweisen kann.
Der Katalog ist ein JSON-Linkset. Jeder Eintrag ist mit der Basis-URL einer API verknüpft und verweist auf ihre maschinenlesbare Beschreibung (service-desc, üblicherweise eine OpenAPI-Datei), die Dokumentation für Menschen (service-doc) und ihre Statusseite. Ein Client liest eine kleine Datei, statt Ihre Dokumentation zu crawlen.
Laut RFC muss die Antwort den Medientyp application/linkset+json verwenden und sollte das Profil https://www.rfc-editor.org/info/rfc9727 enthalten. Wir haben noch keine Daten dazu, welche Agents die Datei abrufen. Es handelt sich jedoch nur um eine statische Datei, die Sie veröffentlichen müssen.
Fragen zu api-catalog
Was ist /.well-known/api-catalog?
Das ist der von RFC 9727 festgelegte Speicherort für eine maschinenlesbare Liste der APIs einer Organisation. Die Datei ist ein JSON-Linkset, das jede API mit ihrer Beschreibung, Dokumentation und Statusseite verknüpft. Clients finden es direkt an diesem Speicherort oder über die Link-Relation api-catalog.
Welchen Content-Type benötigt api-catalog?
RFC 9727 schreibt application/linkset+json vor und empfiehlt den Profilparameter https://www.rfc-editor.org/info/rfc9727. Der nginx-Block auf dieser Seite setzt den Medientyp und den Link-Header. Fügen Sie den Profilparameter selbst hinzu, sofern Ihre Serverkonfiguration dies zulässt.
Benötige ich eine OpenAPI-Datei, um einen Katalog zu veröffentlichen?
Nein. In diesem Generator benötigt jeder Eintrag nur die Basis-URL der API. Links zur Beschreibung, Dokumentation und Statusseite sind optional. Mit einer OpenAPI-Beschreibung kann ein Client Ihre Endpoints ohne Fließtext ermitteln. Fügen Sie sie also hinzu, wenn Sie eine haben.
Wie unterscheidet sich api-catalog von llms.txt?
api-catalog ist ein IETF-RFC, der APIs als JSON-Links für Software auflistet, die sie aufruft. llms.txt ist ein Vorschlag für einen Markdown-Index von Seiten, der sich an Sprachmodelle richtet, die Dokumentation lesen. Die beiden Formate überschneiden sich nicht; Sie können also beide veröffentlichen.