# api-catalog

## Что такое API Catalog?

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

```json
{
  "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-заголовках](/glossary/link-headers) главной страницы:

```http
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 добавьте ссылку на метаданные авторизации:

```json
{
  "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`.

[← Все термины глоссария](/glossary)