agentsready
API / Auth / MCP Средне

API Catalog в /.well-known: как агенты находят ваши API

Что такое /.well-known/api-catalog (RFC 9727), зачем он AI-агентам, минимальный пример linkset, ошибки и как проверить.

Обновлено:

Что это

/.well-known/api-catalog (RFC 9727) — документ по предсказуемому адресу, который ссылается на описания ваших API (OpenAPI, AsyncAPI и т.п.). Формат — linkset (RFC 9264): набор ссылок с rel-типами. Это «оглавление» ваших программных интерфейсов для машин.

Зачем это AI-агентам

Агент, которому нужно не прочитать страницу, а вызвать ваш API, должен сперва его найти. Без каталога он гадает URL или парсит HTML-доки. api-catalog даёт прямой машиночитаемый указатель: вот описание API, вот его endpoints — агент сразу понимает, как с вами интегрироваться.

Минимальный рабочий пример

GET /.well-known/api-catalog HTTP/1.1
{
  "linkset": [
    {
      "anchor": "https://example.com",
      "service-desc": [
        { "href": "https://example.com/openapi.json", "type": "application/openapi+json" }
      ]
    }
  ]
}

Content-Type: application/linkset+json. rel-типы (service-desc, service-doc) указывают на описание и документацию API.

Правильно vs неправильно

ПравильноНеправильно
Лежит по /.well-known/api-catalogПроизвольный путь
application/linkset+json, валидный linksetПросто текст/HTML вместо linkset
Абсолютные href, стандартные relОтносительные ссылки / самодельные rel
Ссылается на реальные, доступные описания APIБитые ссылки на несуществующий OpenAPI

Типичные ошибки

  • Неверный Content-Type — не application/linkset+json.
  • Битые ссылки на описания API (404 на OpenAPI).
  • Относительные href вместо абсолютных.
  • Каталог есть, но не анонсирован через Link-заголовок rel="api-catalog" (см. гайд по Link-заголовкам).

Как проверить

Скан проверит наличие и формат каталога. Вручную:

curl -s https://example.com/.well-known/api-catalog | jq .
curl -sI https://example.com/.well-known/api-catalog | grep -i content-type

Ждём валидный linkset и application/linkset+json.

Источники