API Catalog (RFC 9727)

Что такое API Catalog?

API Catalog (RFC 9727) — JSON-документ в формате linkset по адресу /.well-known/api-catalog, перечисляющий все публичные API сайта. Позволяет AI-агентам автоматически обнаружить доступные API без парсинга документации.

{
  "linkset": [
    {
      "anchor": "https://api.example.com",
      "service-doc": [{ "href": "https://api.example.com/openapi.json" }],
      "service-desc": [{ "href": "https://api.example.com/openapi.yaml" }]
    }
  ]
}

Content-Type должен быть application/linkset+json.

Зачем нужен API Catalog?

AI-агенты, работающие автономно, должны найти точки входа в API. API Catalog — стандартное место для этого: агент делает GET /.well-known/api-catalog и получает полный список доступных ресурсов с документацией.

Ссылка на API Catalog должна присутствовать в Link-заголовках главной страницы:

Link: </.well-known/api-catalog>; rel="api-catalog"

Как реализовать API Catalog?

Создайте файл public/.well-known/api-catalog с Content-Type application/linkset+json. Структура по RFC 9727 — массив linkset, где каждый элемент имеет:

Поле	Обязательно	Описание
anchor	да	URI API-ресурса
service-doc	рекомендуется	Ссылка на документацию (OpenAPI, Swagger)
service-desc	рекомендуется	Ссылка на машиночитаемую схему
status	нет	Статус API (stable, deprecated)

Для OAuth-защищённых API добавьте ссылку на метаданные авторизации:

{
  "linkset": [
    {
      "anchor": "https://api.example.com",
      "service-doc": [{ "href": "https://api.example.com/openapi.json" }],
      "service-desc": [{ "href": "https://api.example.com/openapi.yaml" }],
      "oauth-protected-resource": [{ "href": "https://api.example.com/.well-known/oauth-protected-resource" }]
    }
  ]
}

Как мы проверяем API Catalog?

Сканер выполняет GET /.well-known/api-catalog с заголовком Accept: application/linkset+json, application/json и проверяет:

1. HTTP-статус 200 и Content-Type application/linkset+json или application/json
2. Валидный JSON с корневым массивом linkset
3. Не пустой linkset — хотя бы один элемент с полями anchor + href

Градиентная оценка: 3+ валидных элемента → pass (1.0), 1–2 → warning (0.5), 0 → fail.