12. Заголовки

12.1 Обязательно

  • R-HDR-1. Стандартные HTTP-заголовки используются по назначению:

    • Content-Type — тип тела запроса/ответа (application/json)
    • Accept — ожидаемый тип ответа (application/json)
    • Authorization — аутентификация (Bearer eyJhbGci...)
    • Location — URL созданного ресурса при 201 Created
    • ETag — версия ресурса для кеширования ("33a64df5")
    • If-None-Match — условный GET ("33a64df5")

  • R-HDR-2. Кастомные заголовки используют доменный префикс, единый для всех сервисов проекта/компании. Префикс выбирается один раз и фиксируется в стандартах команды (в примере — Shop-):

    Shop-Request-Id: 550e8400-e29b-41d4-a716-446655440000
Shop-Client-Version: 2.1.0
    • Shop-Request-Id — идентификатор конкретного запроса от клиента (для дедупликации и логирования). Не путать с traceparent (см. R-HDR-4).

  • R-HDR-3. Для POST-запросов, которые должны быть безопасны при повторной отправке, используется заголовок Idempotency-Key.

    POST /api/v1/orders
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

  • R-HDR-4. Для распределённой трассировки используется стандарт W3C Trace Context. Заголовок traceparent передаётся клиентом или генерируется на входе и прокидывается через все сервисы в цепочке.

    Формат: traceparent: {version}-{trace-id}-{parent-id}-{trace-flags}

    • version — версия формата, сейчас всегда 00
    • trace-id — 32 hex-символа, уникальный ID всей цепочки вызовов
    • parent-id — 16 hex-символов, ID текущего span'а
    • trace-flags — 2 hex-символа (например, 01 = sampled)

    Пример:

    traceparent: 00-1f2a8b6c7d3e4f5a9b0c1d2e3f4a5b6c-7a8b9c0d1e2f3a4b-01

    Правила:

    • Если клиент прислал traceparent — сервис использует его trace-id и создаёт новый parent-id для своего span'а.
    • Если клиент не прислал — сервис генерирует traceparent на входе.
    • trace-id из traceparent используется как traceId в теле ошибки RFC 9457 (см. R-ERR-1 в Ошибки).
    • Опциональный tracestate — для vendor-специфичных данных.
    traceparent: 00-1f2a8b6c7d3e4f5a9b0c1d2e3f4a5b6c-7a8b9c0d1e2f3a4b-01
tracestate: vendor1=value1,vendor2=value2

12.2 Запрещено

  • R-HDR-X1. Префикс X- в кастомных заголовках. Устарел по RFC 6648.