Generator katalogu API
Wymień raz swoje publiczne API i wygeneruj zestaw linków JSON wymagany przez RFC 9727 pod adresem /.well-known/api-catalog oraz blok nginx, który udostępnia go z właściwym typem MIME.
{
"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;
}
Prześlij plik pod adres /.well-known/api-catalog i udostępnij go jako application/linkset+json. Blok nginx ustawia ten typ i dodaje nagłówek Link z rel="api-catalog", wymagany przez RFC 9727 w odpowiedziach na żądania HEAD.
Dlaczego warto opublikować katalog API
Agent, który chce wywołać Twoje API, musi najpierw je znaleźć. Opublikowany w czerwcu 2025 RFC 9727 wyznacza stały punkt początkowy dla takiego wyszukiwania: well-known URL /.well-known/api-catalog oraz relację linku api-catalog, za pomocą której dowolna strona może wskazać ten katalog.
Katalog to zestaw linków w formacie JSON. Każdy wpis wskazuje podstawowy URL API i prowadzi do jego opisu czytelnego maszynowo (service-desc, zwykle pliku OpenAPI), dokumentacji dla użytkowników (service-doc) oraz strony statusu. Klient odczytuje jeden niewielki plik zamiast przeszukiwać dokumentację.
RFC wymaga, aby odpowiedź używała typu application/linkset+json, i zaleca dodanie profilu https://www.rfc-editor.org/info/rfc9727. Nie mamy jeszcze danych o tym, które agenty pobierają ten plik, ale do opublikowania wystarczy jeden statyczny plik.
Pytania o api-catalog
Czym jest /.well-known/api-catalog?
To lokalizacja określona w RFC 9727, przeznaczona na czytelną maszynowo listę API danej organizacji. Plik to zestaw linków JSON, który wskazuje dla każdego API jego opis, dokumentację i status. Klienci mogą znaleźć go bezpośrednio pod tym adresem lub za pomocą relacji linku api-catalog.
Jakiego nagłówka Content-Type wymaga api-catalog?
RFC 9727 wymaga wartości application/linkset+json i zaleca dodanie parametru profile o wartości https://www.rfc-editor.org/info/rfc9727. Blok nginx na tej stronie ustawia typ MIME i nagłówek Link; parametr profile dodaj samodzielnie, jeśli pozwala na to konfiguracja serwera.
Czy do opublikowania katalogu potrzebuję pliku OpenAPI?
Nie. W tym generatorze każdy wpis wymaga tylko podstawowego URL API, a linki do opisu, dokumentacji i strony statusu są opcjonalne. Opis OpenAPI pozwala klientowi poznać endpointy bez czytania dokumentacji tekstowej, więc dodaj go, jeśli go masz.
Czym api-catalog różni się od llms.txt?
api-catalog to RFC IETF, które wymienia API jako linki JSON dla oprogramowania, które z nich korzysta. llms.txt to propozycja indeksu stron w Markdown, przeznaczonego dla modeli językowych czytających dokumentację. Nie pokrywają się ze sobą, więc można opublikować oba.