Link headers (RFC 8288)

Что такое 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:

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

Next.js middleware:

response.headers.set('Link',
  '</.well-known/api-catalog>; rel="api-catalog", </status>; rel="status"');

Astro middleware (src/middleware.ts):

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 — заголовок отсутствует.