URL, HTTP-метод, параметры запроса и JSON обычно описаны.
А вот следующие 5 вещей встречаются гораздо реже, хотя именно про них потом начинаются вопросы у разработчиков и проблемы в проде 👇
1️⃣ Кэширование
Если данные можно кэшировать — это должно быть описано в требованиях.
Чаще всего — для операций получения данных (GET).
▫️ Что кэшируем?
▫️ Где: Backend, Redis, другое хранилище?
▫️ Какой TTL (время жизни)?
▫️ Что входит в ключ кэша?
▫️ Когда и кем кэш инвалидируется?
Написать просто «результат кэшировать на 10 минут» часто недостаточно.
2️⃣ Идемпотентность
Что произойдёт, если один и тот же запрос придёт дважды?
Особенно критично для создания заказов, платежей, бронирований и других изменяющих операций.
▫️ Выполним операцию повторно?
▫️ Вернём результат первого запроса?
▫️ Как определим, что запрос повторный?
Пользователь нажал кнопку два раза — система должна знать, что с этим делать.
3️⃣ Единый формат ошибок от API
Не так, что один метод возвращает:
{"error": "Not found"}
другой:
{"message": "Something went wrong"}
а третий свою структуру.
Для API должна быть определена единая модель возврата ошибок:
✅ единая структура JSON-ошибки
✅ правила использования HTTP-статусов
Иначе каждый новый метод постепенно начинает жить своей жизнью.
4️⃣ Что делать, если операция выполнилась только частично
Например:
Backend сохранил данные в БД → вызвал внешнюю систему → внешний вызов завершился ошибкой.
Или:
внешняя система выполнила операцию → а сохранить результат в нашей БД не получилось.
▫️ Что откатываем?
▫️ Что повторяем?
▫️ Нужна ли компенсационная операция?
▫️ В каком состоянии оставляем данные?
Особенно важно в интеграционных сценариях, где один пользовательский запрос запускает несколько операций.
5️⃣ Логирование и мониторинг
Пользователь пишет:
«Вчера в 15:42 я оплатил заказ, но статус не изменился».
Что дальше?
▫️ Есть ли requestId / correlationId?
▫️ Передаётся ли он между сервисами?
▫️ Что пишем в логи?
▫️ Какие технические и бизнес-метрики собираем?
▫️ На какие ошибки должны срабатывать алерты?
Требования к логированию и мониторингу — такая же часть постановки задачи, как JSON запроса и ответа.
Ни один из этих пунктов технически не выглядит чем-то сверхсложным.
Но именно их легко пропустить, а потом выяснять, как должна вести себя система, уже вместе с разработчиками. Иногда в проде 🥲
#RestApiGA
📱 GetAnalyst | 💙 VK | 💬 Max