Генератор каталога API
Перечислите публичные API и получите JSON linkset, который RFC 9727 требует размещать по адресу /.well-known/api-catalog, а также блок nginx для его отдачи с нужным типом содержимого.
{
"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;
}
Загрузите файл по адресу /.well-known/api-catalog и отдавайте его с типом application/linkset+json. Блок nginx задаёт этот тип и добавляет заголовок Link с rel="api-catalog", который RFC 9727 требует для запросов HEAD.
Зачем публиковать каталог API
Агенту, который хочет вызвать ваш API, сначала нужно его найти. RFC 9727, опубликованный в июне 2025 года, задаёт для поиска стандартную точку входа: well-known URL /.well-known/api-catalog и отношение ссылки api-catalog, с помощью которого на него может указывать любая страница.
Каталог представляет собой linkset в формате JSON. Каждая запись привязана к базовому URL API и содержит ссылки на его машиночитаемое описание (service-desc, обычно файл OpenAPI), документацию для людей (service-doc) и страницу статуса. Клиенту достаточно прочитать один небольшой файл вместо обхода документации.
Согласно RFC, ответ должен иметь тип application/linkset+json и рекомендуется указывать профиль https://www.rfc-editor.org/info/rfc9727. Пока неизвестно, какие агенты запрашивают этот файл, но для публикации достаточно одного статического файла.
Вопросы о api-catalog
Что такое /.well-known/api-catalog?
Это адрес, определённый RFC 9727 для машиночитаемого списка API организации. Файл представляет собой JSON linkset со ссылками от каждого API на его описание, документацию и страницу статуса. Клиенты могут найти его напрямую по этому адресу или через отношение ссылки api-catalog.
Какой Content-Type нужен для api-catalog?
RFC 9727 указывает, что тип должен быть application/linkset+json, а в параметре profile рекомендуется передавать https://www.rfc-editor.org/info/rfc9727. Блок nginx на этой странице задаёт тип содержимого и заголовок Link. Если конфигурация сервера это позволяет, добавьте параметр profile самостоятельно.
Нужен ли файл OpenAPI для публикации каталога?
Нет. В этом генераторе для каждой записи нужен только базовый URL API; ссылки на описание, документацию и страницу статуса необязательны. Описание OpenAPI позволяет клиенту узнать о ваших endpoints, не читая текстовую документацию, поэтому добавьте его, если оно у вас есть.
Чем api-catalog отличается от llms.txt?
api-catalog — это стандарт IETF RFC, который перечисляет API в виде JSON-ссылок для программ, вызывающих эти API. llms.txt — это предложение создать индекс страниц в Markdown для языковых моделей, которые читают документацию. Эти форматы решают разные задачи, поэтому можно публиковать оба.