Примеры

Здесь собраны сценарии, которые встречаются чаще остальных. Каждый разобран до уровня «что уходит, что приходит и на что смотреть в ответе», без обвязки конкретного языка — переложить на свой стек несложно.

Создание объекта

Самый частый вызов. В теле — обязательные поля и ключ идемпотентности; в ответе — созданный объект целиком, вместе с идентификатором и меткой времени. Ответ стоит сохранять как есть, а не собирать объект на клиенте из того, что отправили: сервер нормализует часть полей и может добавить вычисляемые.

Типичная ошибка новичка — считать успехом код 202. Он означает, что запрос принят в обработку, а не что объект создан; итог придёт событием или обнаружится при следующем чтении.

Пакетная загрузка

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

Размер пачки подбирается под лимит тела запроса, а не под красивое круглое число: слишком большая пачка отвергается целиком.

Выборка с фильтрами

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