tigir.com

Проектирование Rest Api: соглашения, обработка ошибок, пагинация, версионирование и документация

Чтобы выстроить надежное проектирование REST API, зафиксируйте контракт ресурсов и URI, задайте правила для методов и идемпотентности, унифицируйте формат ошибок, выберите пагинацию и стратегию версионирования, а затем автоматизируйте документацию и примеры в CI. Такой порядок снижает регрессы при разработке REST API и упрощает поддержку клиентов.

Практические выводы для проектирования REST API

  • Начинайте с контракта: ресурсы, поля, фильтры и форматы ответов важнее эндпоинтов.
  • Делайте идемпотентные операции предсказуемыми: повтор запроса не должен неожиданно менять состояние.
  • Ошибки — часть контракта: единый формат и стабильные коды экономят время интеграций.
  • Пагинация в REST API должна быть совместима с сортировкой и изменениями данных; предпочитайте курсоры при высокой конкуренции записей.
  • Версионирование REST API планируйте заранее: совместимость, миграция и срок жизни версий должны быть явными.
  • Документация REST API должна собираться из кода и проверяться в CI так же строго, как и тесты.

Контракт API: ресурсы, URI и соглашения именования

Кому подходит: командам, где несколько клиентов (web/mobile/партнеры), есть интеграции между сервисами и требуется долгоживущий публичный интерфейс.

Когда не стоит усложнять: короткоживущие внутренние прототипы или одноразовые админские эндпоинты — иногда быстрее сделать минимальный контракт и переработать после подтверждения ценности. Риск: «прототип» часто становится продакшеном без времени на рефакторинг; заложите хотя бы единый формат ошибок и нейминг.

Соглашения, которые обычно окупаются

  • Ресурсы — существительные во множественном числе: /users, /orders, вложенность — только при реальной принадлежности: /users/{userId}/orders.
  • Единый стиль полей JSON (например, snake_case или camelCase) и единая кодировка дат (обычно ISO 8601 строкой).
  • Фильтры/сортировки/выбор полей — параметрами запроса, а не «магией» в пути.

Пример: список ресурсов с фильтром и сортировкой

Запрос

GET /orders?status=paid&sort=-created_at&limit=50

Ответ

{
  "data": [
    {"id": "ord_123", "status": "paid", "created_at": "2026-03-28T10:15:00Z"}
  ],
  "meta": {"limit": 50}
}

Проектирование операций: методы, идемпотентность и граничные сценарии

На этом этапе важнее всего заранее описать поведение методов и «края» (повторы, таймауты, конкурентные изменения). Это напрямую влияет на разработку REST API: клиенты будут ретраить запросы, а прокси/SDK — переупорядочивать и повторять.

Что понадобится до начала

  • Список пользовательских сценариев (минимум: создать/изменить/прочитать/удалить, поиск, массовые операции).
  • Определенные свойства операций: идемпотентность, допустимость ретраев, требования к консистентности.
  • Доступ к логам/трассировкам (correlation id), чтобы диагностировать повторы и гонки.
  • Средства контрактного тестирования (хотя бы коллекция запросов + автопроверки схем) и staging-среда.

Практика: выбор метода и ожидаемая идемпотентность

  • GET — чтение, безопасен, должен быть идемпотентным.
  • POST — создание/команда, обычно не идемпотентен; для безопасных ретраев вводите Idempotency-Key.
  • PUT — полная замена ресурса (или предсказуемый апсерт по ключу), идемпотентен при одинаковом теле.
  • PATCH — частичное изменение, часто не идемпотентен, если используется «инкремент»; делайте операции явными.
  • DELETE — удаление, обычно идемпотентен (повтор = ресурс уже удален).

Пример: идемпотентное создание через Idempotency-Key

Запрос

POST /payments
Idempotency-Key: 9b7a2f1d-2aab-4f0b-a5bb-3e5c0f0a5c2d
Content-Type: application/json

{"order_id":"ord_123","amount":1000,"currency":"RUB"}

Ответ (при повторе)

{
  "data": {"id":"pay_777","order_id":"ord_123","status":"created"}
}

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

Обработка ошибок: стандарты ответов и схемы кодов

Риски и ограничения, которые важно учесть заранее

  • Разные форматы ошибок в разных эндпоинтах ломают клиентские SDK и усложняют поддержку; откат дорогой, потому что клиенты уже завязались на «как получилось».
  • Смешивание 4xx/5xx приводит к неверным ретраям: клиент может бесконечно повторять невалидный запрос или, наоборот, не повторять временную ошибку.
  • Утечка внутренних деталей (SQL, стеки, имена сервисов) повышает риск безопасности; нужен санитарный слой сообщений.
  • Нестабильные коды ошибок (сегодня одно значение, завтра другое) ломают автоматические обработчики на клиентах; меняйте только через версию/миграцию.

Пошаговый процесс внедрения единого формата ошибок

  1. Определите контракт ошибки. Зафиксируйте обязательные поля (например: error.code, error.message, error.details, trace_id) и договоритесь, что формат одинаков для всех ответов с ошибкой.

    • Последствие пропуска: клиенты пишут обработку «по строке», а не по коду.
  2. Сопоставьте бизнес-ошибки с HTTP-статусами. Опишите правила: валидация = 400/422, отсутствие прав = 403, не найдено = 404, конфликт = 409, лимиты = 429, временные сбои = 503.

    • Путь отката: если сейчас статусы «плавают», начните с добавления error.code и стабилизируйте статусы позже.
  3. Стандартизируйте структуру details для валидации. Сделайте массив нарушений с указанием поля и причины, чтобы UI мог подсветить конкретные ошибки.

    • Ограничение: не включайте в message персональные данные и внутренние идентификаторы.
  4. Добавьте корреляцию и наблюдаемость. Возвращайте trace_id и логируйте его на всех слоях; для 5xx фиксируйте тип, компонент и ключевые контексты без секретов.
  5. Закрепите контракт тестами и линтингом схем. Введите контрактные тесты на форму ошибок для каждого эндпоинта и прогоняйте их в CI, чтобы изменения не просачивались в прод.

Пример: ошибка валидации с деталями

Проектирование REST API: соглашения, ошибки, пагинация, версионирование и документация - иллюстрация

Ответ

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Некорректные параметры запроса",
    "details": [
      {"field": "amount", "reason": "must_be_positive"}
    ]
  },
  "trace_id": "2f4c1c2b9c3a4a7d"
}

Пример: конфликт версии ресурса (оптимистическая блокировка)

Проектирование REST API: соглашения, ошибки, пагинация, версионирование и документация - иллюстрация

Запрос

PATCH /orders/ord_123
If-Match: "v7"
Content-Type: application/json

{"status":"cancelled"}

Ответ

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error": {
    "code": "VERSION_CONFLICT",
    "message": "Ресурс был изменен, обновите данные и повторите попытку"
  },
  "trace_id": "b81f0b6c4e1a4b09"
}

Пагинация в реальной нагрузке: подходы, параметры и примеры

Пагинация в REST API должна сохранять предсказуемость при параллельных вставках/удалениях, не допускать пропусков и дублей, и быть понятной в отладке. Выбор влияет на кеширование, производительность индексов и сложность клиента.

Подход Как выглядит Плюсы Минусы/риски Когда выбирать
Offset/Limit ?offset=100&limit=50 Просто для клиента, легко «прыгать» по страницам Дорого на больших смещениях; возможны пропуски/дубли при изменениях данных Небольшие наборы данных, админки, стабильная выборка
Page/Size ?page=3&size=20 Понятная семантика страниц Те же проблемы, что у offset; часто маскирует реальную стоимость запросов UI с нумерацией страниц при малом объеме
Cursor (seek) ?limit=50&cursor=... Стабильнее под нагрузкой, обычно быстрее на больших объемах Сложнее реализовать и дебажить; нельзя «перейти на страницу 10» без обхода Ленты, журналы событий, большие таблицы, частые вставки

Пример: курсорная пагинация с сортировкой

Запрос

GET /events?limit=50&cursor=eyJjcmVhdGVkX2F0IjoiMjAyNi0wMy0yOFQxMDowMDowMFoiLCJpZCI6ImV2Xzk5OSJ9&sort=created_at,id

Ответ

{
  "data": [
    {"id":"ev_1000","created_at":"2026-03-28T10:01:00Z","type":"order.paid"}
  ],
  "page": {
    "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wMy0yOFQxMDowMTowMFoiLCJpZCI6ImV2XzEwMDAifQ==",
    "limit": 50
  }
}

Риск и откат: если курсор строится только по времени без tie-breaker (например, id), возможны дубли при одинаковых таймстемпах. Откат — добавить стабильную сортировку по двум полям и пересчитать курсоры.

Проверка, что пагинация работает корректно

  • Зафиксировано правило сортировки по умолчанию (и оно задокументировано).
  • Для курсора используется стабильный ключ (таймстемп + уникальный id), а не только «created_at».
  • Повтор запроса с тем же курсором возвращает тот же набор (при неизменных данных) или предсказуемые изменения (при изменениях данных это описано).
  • Параметры limit имеют верхнюю границу, при превышении возвращается понятная 4xx-ошибка.
  • Ответ содержит указатели навигации (next_cursor и/или has_more) и они не противоречат данным.
  • Фильтры применяются до пагинации (иначе страницы «плавают»).
  • Поля, участвующие в сортировке/курсоре, индексированы или подтверждены нагрузочными тестами.
  • Для больших выборок нет деградации из-за больших offset (если offset поддерживается — он ограничен).

Версионирование API: стратегии, совместимость и план миграции

Версионирование REST API — это не только «v1/v2», а процесс управления совместимостью. Выбирайте стратегию исходя из числа клиентов, скорости релизов и возможности принудительных обновлений.

Пример: версия в пути

Запрос

GET /v1/orders/ord_123

Ответ

{
  "data": {"id":"ord_123","status":"paid"}
}

Пример: эволюция поля без мажорной версии (совместимое расширение)

Ответ

{
  "data": {"id":"ord_123","status":"paid","paid_at":"2026-03-28T10:15:00Z"}
}

Риск: если клиенты используют строгую валидацию «без дополнительных полей», расширение может сломать интеграцию. Путь отката: добавить режим tolerant-валидации в SDK или согласовать контракт (например, JSON Schema с additionalProperties по политике команды).

Частые ошибки при вводе версий и как их избежать

  • Менять смысл поля без смены версии (например, валюту/единицы измерения) — делайте новое поле или новую версию.
  • Удалять поля сразу — сначала объявите депрекацию и поддерживайте переходный период.
  • Считать добавление обязательного поля «минорным» — для клиентов без него это ломающая правка.
  • Версионировать «всё подряд» вместо конкретных контрактов — версионируйте API как продукт, а не отдельные микросервисы без координации.
  • Не иметь политики совместимости (что можно менять без версии) — зафиксируйте правила и проверяйте их ревью/тестами.
  • Не иметь плана миграции — заранее определите сроки поддержки, метрики использования версии и коммуникацию клиентам.
  • Поддерживать бесконечно много версий — ограничьте число активных и автоматизируйте отключение неиспользуемых.
  • Скрывать версию «только в документации» — версия должна быть определяема в запросе (путь/заголовок/медиа-тип) и логах.

Документация и примеры: генерация, поддержка и CI-интеграция

Документация REST API должна быть частью поставки: обновляться вместе с кодом, содержать примеры запрос/ответ и проверяться на согласованность. Это уменьшает расхождения между «как задумано» и «как работает» и ускоряет интеграции.

Варианты организации документации и когда они уместны

Вариант Когда уместен Плюсы Риски Как откатиться/смягчить
Спецификация OpenAPI как «источник истины» Публичные API, несколько команд/клиентов, нужны SDK/генерация Единый контракт, автогенерация клиентов и моков, проще контрактные тесты Спека отстает от кода, если нет дисциплины Гейт в CI: сборка падает при несовпадении схем/примеров
Код-first + генерация спек из аннотаций/схем Быстрая разработка, сильная типизация, акцент на реализацию Меньше дублирования, ближе к реальному поведению Труднее поддерживать качественные описания и примеры Шаблоны описаний, обязательные примеры, ревью документации как кода
Документация как портал (handbook) + живые примеры Нужны сценарии, гайды, типовые интеграции, тонкости бизнес-логики Лучше обучает, показывает «как использовать» Быстро устаревает без привязки к релизам Версионировать страницы, привязывать к тегам релизов, автопроверки примеров

Пример: минимальный фрагмент, который стоит включать в описание эндпоинта

  • Назначение ресурса и права доступа.
  • Пример запроса и успешного ответа.
  • Перечень возможных ошибок (коды + значения error.code), включая 409/429.

Пример: выдержка из описания для эндпоинта создания

Запрос

POST /v1/orders
Content-Type: application/json

{"items":[{"sku":"sku_1","qty":2}]}

Ответ

HTTP/1.1 201 Created
Content-Type: application/json

{"data":{"id":"ord_123","status":"created"}}

Ответы на типичные сложности при внедрении

Где хранить «источник истины»: в коде или в спецификации?

Выберите один главный артефакт и закрепите это в процессе ревью. Если «источник истины» расплывчатый, документация REST API неизбежно начнет расходиться с реальностью.

Нужно ли всегда использовать вложенные URI типа /users/{id}/orders?

Только когда связь действительно иерархическая и упрощает авторизацию/контекст. Для поиска по пользователю часто достаточно /orders?user_id=..., иначе растет связность и сложнее переиспользовать ресурсы.

Какие ошибки обязательно стандартизировать в первую очередь?

Валидацию (400/422), конфликт (409), лимиты (429) и временную недоступность (503). Эти классы чаще всего требуют автоматической обработки и влияют на ретраи.

Как выбрать между offset и cursor для «списков»?

Если возможны частые вставки/удаления и большие объемы — выбирайте курсоры; это типичная «пагинация в REST API» для лент и событий. Offset оставляйте для небольших наборов и случаев, где важна навигация по страницам.

Что считать ломающим изменением для версий?

Удаление или переименование поля, изменение типа/семантики, введение нового обязательного поля, изменение правил сортировки по умолчанию. В таких случаях версионирование REST API или миграционный слой обязательны.

Можно ли версионировать через заголовок вместо /v1 в пути?

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

Как не сломать клиентов при расширении ответа новыми полями?

Договоритесь о tolerant-парсинге у клиентов и явно зафиксируйте правило совместимости в контракте. Если клиенты строгие, вводите фичефлаги/параметры выборки полей или мажорную версию.