Главная › REST API Style Guide › Заголовки и трассировка

REST API Style Guide: Заголовки и трассировка

HTTP-заголовки в REST API: Idempotency-Key для денежных операций, W3C Trace Context для distributed tracing, стандартные и кастомные заголовки.

Статья внедрена в скилл AI-агента ucp-api-review / ucp-api-design REST API заголовки traceparent

REST API заголовки traceparent: 12. Заголовки

12.1. Стандартные HTTP-заголовки

REST API заголовки traceparent — - Content-Type -- тип тела запроса/ответа. Пример: application/json

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

12.2. Кастомные заголовки -- без префикса X-

Префикс X- устарел (RFC 6648). Используйте доменный префикс:

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

12.3. Идемпотентность -- Idempotency-Key

Для POST-запросов, которые должны быть безопасны при повторной отправке:

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

12.4. Трассировка -- traceparent (W3C Trace Context)

Для распределённой трассировки используется стандарт 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 (раздел 13)
  • Опциональный заголовок tracestate -- для vendor-специфичных данных трассировки (ключ-значение пары)
traceparent: 00-1f2a8b6c7d3e4f5a9b0c1d2e3f4a5b6c-7a8b9c0d1e2f3a4b-01
tracestate: vendor1=value1,vendor2=value2
← Предыдущая
JSON и формат ответов