# link-headers

## Что такое Link headers?

HTTP `Link` response header (RFC 8288) — это заголовок ответа, которым сервер аннотирует страницу ссылками на связанные машиночитаемые ресурсы. AI-агенты используют эти заголовки для автоматического обнаружения API, документации и каталогов.

```
Link: </.well-known/api-catalog>; rel="api-catalog",
      </terms>; rel="terms-of-service",
      </status>; rel="status"
```

## Зачем сайту Link headers?

`Link` headers — стандартный механизм service discovery без парсинга HTML. Агент, делая запрос к главной странице, сразу видит в заголовках ответа ссылки на все важные метаресурсы.

Особенно важно для API-сервисов: клиент находит API-каталог, OAuth discovery endpoint или документацию без предварительного знания URL.

Релевантные `rel`-значения для агентов:

| rel | Что указывает |
|---|---|
| `api-catalog` | API Catalog (RFC 9727) |
| `service-doc` | Документация сервиса |
| `service-desc` | Описание сервиса (OpenAPI) |
| `status` | Страница статуса |
| `terms-of-service` | Условия использования |

## Как настроить Link headers?

**Nginx:**
```nginx
add_header Link '</.well-known/api-catalog>; rel="api-catalog", </terms>; rel="terms-of-service"';
```

**Next.js middleware:**
```typescript
response.headers.set('Link',
  '</.well-known/api-catalog>; rel="api-catalog", </status>; rel="status"');
```

**Astro middleware (`src/middleware.ts`):**
```typescript
import { defineMiddleware } from 'astro:middleware';

export const onRequest = defineMiddleware((ctx, next) => {
  const response = await next();
  response.headers.set('Link',
    '</.well-known/api-catalog>; rel="api-catalog"');
  return response;
});
```

## Как мы проверяем Link headers?

Сканер делает `HEAD /` (с fallback на `GET` при HTTP 405) и проверяет заголовок `Link` в ответе.

1. **Наличие заголовка `Link`** — если отсутствует, статус `fail`
2. **Парсинг ссылок** — извлекаем все пары `<url>; rel="..."`
3. **Релевантные rel-значения** — ищем хотя бы одно из: `api-catalog`, `service-doc`, `service-desc`, `status`, `terms-of-service`

Статус **pass** (1.0) — найдено хотя бы одно релевантное rel-значение. Статус **warning** (0.5) — Link header есть, но без релевантных rel. Статус **fail** — заголовок отсутствует.

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