Заголовки
контракта

§1Три неприятности и три заголовка

Обратите внимание: ни один из этих случаев не решается в теле ответа. Всё это — договорённости о заголовках, и они одинаковы для любого API, который их поддерживает.

§2ETag: версия представления

ETag — короткая строка, которая меняется при каждом изменении ресурса. Клиенту не важно, как она вычисляется; важно, что одинаковый ETag означает одинаковое содержимое. Учебный сервис считает его от полей обращения.

HTTP/1.1 200
etag: "4fec2a976840743a"
x-request-id: support-case-1842
content-type: application/json

ETag отдаётся с каждым чтением и с каждой записью — в том числе при создании. Дальше клиент использует его двумя способами, и это два разных заголовка запроса.

§3If-None-Match: не присылать то же самое

Сценарий: список обращений на экране обновляется раз в несколько секунд, но меняется редко. Без условного запроса клиент каждый раз скачивает одно и то же.

1. Первое чтение. Клиент получает 200, тело и ETag: "4fec2a976840743a". Значение он запоминает.
2. Следующее чтение. Клиент шлёт If-None-Match: "4fec2a976840743a".
3. Ничего не изменилось. Сервис отвечает 304 Not Modified — без тела. Клиент рисует то, что уже держит в памяти.
4. Что-то изменилось. Сервис отвечает 200, новым телом и новым ETag.

HTTP/1.1 304
etag: "4fec2a976840743a"
x-request-id: d1992782-8a1d-444f-b2ba-1cf8891806b6

Тела в таком ответе нет: по стандарту у 304 его быть не должно. Выигрыш тем заметнее, чем больше ресурс и чаще опрос; у GitHub такой ответ вдобавок не списывается из лимита запросов.

§4If-Match: потерянное изменение

Потерянное изменение выглядит так. Двое открыли одно обращение. Первый дописал описание и сохранил. Второй, ничего не зная, сохранил свою версию — и правка первого исчезла бесследно, без единой ошибки.

Аня  GET  /tickets/42   -> status: open, description: "…"
Борис GET  /tickets/42   -> то же самое
Аня  PATCH /tickets/42  -> description дописан        # 200
Борис PATCH /tickets/42  -> status: closed             # 200, правка Ани затёрта

С условным запросом второе сохранение не проходит: сервис видит, что версия изменилась.

Борис PATCH /tickets/42
      If-Match: "4fec2a976840743a"    # версия, прочитанная до правки Ани
      -> 412 Precondition Failed

HTTP/1.1 412
x-request-id: 8952af24-1c19-4801-8f28-181a89f6265f
content-type: application/problem+json

{
  "type": "https://…/problems/http-412",
  "title": "Precondition failed",
  "status": 412,
  "detail": "Ticket was changed after the version in If-Match was read",
  "instance": "/api/v1/tickets/a8d04cb9-87ea-49b9-8ef6-ba10bbbad82b"
}

Дальше дело клиента: перечитать обращение, показать человеку, что изменилось, и предложить сохранить поверх. Изменение при этом не теряется молча: клиент получает явный отказ и может его обработать.

§5Idempotency-Key: потерянный ответ

Метод POST не идемпотентен: два одинаковых запроса создают два ресурса. Обычно это правильно, но не тогда, когда второй запрос — повтор первого, ответ на который потерялся в сети.

Проверка на учебном сервисе: два запроса с одинаковым ключом дали одно и то же обращение — id совпал, общее число выросло на единицу, а не на две.

HTTP/1.1 201
etag: "72d232d249fabd6e"
location: /api/v1/tickets/6dfeb4e3-497b-4d62-8270-40dace132b9f
x-ratelimit-limit: 60
x-ratelimit-remaining: 57

тот же id: True        # 6dfeb4e3-…-40dace132b9f
всего обращений: 4      # не 5

Важная тонкость: ключ связан с телом запроса. Если прислать тот же ключ с другим телом, это не повтор, а ошибка клиента — и сервис прямо об этом говорит:

HTTP/1.1 422
{
  "title": "Validation error",
  "status": 422,
  "detail": "Idempotency-Key was already used with a different request body",
  "instance": "/api/v1/tickets"
}

Отсюда и два решения учебного проекта: срок хранения 24 часа и сверка тела запроса. Оба взяты из этого правила, а не придуманы.

§6Лимиты и Retry-After

Ограничение частоты защищает сервис от одного невнимательного клиента, из-за которого плохо становится всем. Но отказ должен быть понятным: клиент обязан узнать, сколько ему осталось и когда можно снова. Сам код 429 Too Many Requests описан в RFC 6585, раздел 4, а набор сопровождающих заголовков стандартом не закреплён — его берут из практики.

HTTP/1.1 201
x-ratelimit-limit: 2
x-ratelimit-remaining: 0
x-ratelimit-reset: 60

HTTP/1.1 429
retry-after: 60
x-ratelimit-limit: 2
x-ratelimit-remaining: 0
x-ratelimit-reset: 60

{ "title": "Too many requests", "status": 429,
  "detail": "Write limit of 2 requests per minute exceeded" }

§7X-Request-Id: сшивка журналов

Этот заголовок связывает ответ клиента с записью в журнале сервера. Учебный сервис добавляет его к каждому ответу, а если клиент прислал свой — сохраняет присланный.

VALID_REQUEST_ID = re.compile(r"^[A-Za-z0-9._-]{1,128}$")

incoming = request.headers.get("X-Request-Id")
request_id = incoming if incoming and VALID_REQUEST_ID.match(incoming) else str(uuid4())

Проверка обязательна: чужое значение уходит в журнал, и без ограничения длины и набора символов в журнал можно записать что угодно. Не подошло — сервис выдаёт своё значение, а не отказывает в запросе.

HTTP/1.1 200
etag: "4fec2a976840743a"
x-request-id: support-case-1842

Имена разные, назначение одно: у каждого запроса есть метка, по которой его находят в журналах всех участников. Имя может быть любым, но оно должно быть выбрано и записано в контракте.

§8Почему браузер не видит заголовки

Частый случай: в терминале заголовки есть, а страница их не видит. Причина не в сервисе, а в правилах браузера: со страницы другого источника доступны только простые заголовки плюс те, что сервис разрешил явно.

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:5173"],
    expose_headers=["ETag", "Location", "X-Request-Id", "Retry-After",
                    "Deprecation", "Sunset",
                    "X-RateLimit-Limit", "X-RateLimit-Remaining", "X-RateLimit-Reset"],
)

access-control-allow-origin: http://localhost:5173
access-control-expose-headers: ETag, Location, X-Request-Id, Retry-After, Deprecation,
                               Sunset, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Отсюда практическое правило: добавляя в контракт новый заголовок ответа, проверьте, нужен ли он веб-клиенту. Если нужен, впишите его в expose_headers тем же изменением, иначе заголовок будет существовать для curl и не существовать для страницы.