Stage 1. HTTP Methods: GET, POST, PUT, DELETE
HTTP-метод — это не декоративное поле в запросе, а формальная часть контракта между клиентом и сервером. Когда команда выбирает метод осознанно, API становится предсказуемым: его проще документировать, тестировать, кешировать и безопасно повторять при сетевых сбоях. Когда метод выбран “на глаз”, проблемы проявляются не сразу, но затем накапливаются: неожиданно дублируются операции, ломаются ретраи, появляются спорные инциденты в мониторинге.
Самая полезная идея для новичка звучит так: метод должен выражать намерение операции. GET означает чтение состояния без изменения бизнес-данных. POST означает создание нового ресурса или запуск команды, где повтор может дать новый эффект. PUT означает полную замену состояния ресурса по известному URI. DELETE означает удаление ресурса. Эти различия кажутся простыми, но именно они определяют поведение инфраструктуры вокруг вашего API.
GET /api/orders/42
POST /api/orders
PUT /api/orders/42
DELETE /api/orders/42
Почему это важно в реальном проекте? Потому что запросы живут не только внутри контроллера. Их обрабатывают браузеры, мобильные SDK, API-шлюзы, кеширующие прокси, балансировщики и системы повторов. Например, чтение через GET может кешироваться. Если вы “случайно” меняете состояние через GET, система становится опасно непредсказуемой: автоматический префетч страницы или повтор в сети может запустить бизнес-действие второй раз.
Отдельно стоит понять идемпотентность. Идемпотентный запрос можно отправить повторно, и итоговое состояние не изменится по сравнению с первым успешным выполнением. Поэтому PUT и DELETE обычно проектируют идемпотентными, а POST — нет. Это не академическая терминология, а практическая база для retry-логики. Если команда не различает эти сценарии, повтор запроса в платежах или заказах легко превращается в дубли.
POST /api/payments
Idempotency-Key: 7c1f9c91-2f74-4d0f-9f3d-7c2cbcb7c5a1
Для критичных операций полезно добавлять Idempotency-Key, чтобы сетевой повтор возвращал уже зафиксированный результат, а не создавал новый.
Метод всегда должен проектироваться вместе со статус-кодом. Создание через POST обычно возвращает 201 Created, чтение через GET — 200 OK, удаление через DELETE часто — 204 No Content. Когда API отвечает “всегда 200”, клиент теряет протокольный смысл и вынужден угадывать исход по телу ответа. Это ухудшает стабильность интеграций и осложняет поддержку.
Типичная ошибка новичка — использовать POST для всех операций “чтобы быстрее”. Сначала кажется удобно, но через несколько релизов API превращается в набор команд без понятной модели. Другая распространенная ошибка — endpoint вида GET /api/orders/42/confirm, который меняет состояние. Такой маршрут может пройти ручной тест, но в продакшене будет генерировать трудноуловимые дефекты из-за кешей, повторов и фоновых вызовов.
Практическое правило можно сформулировать так: сначала описываем бизнес-намерение операции, потом выбираем метод, затем фиксируем статус-коды и политику повторов. Если команда придерживается этого порядка, даже большой API остается читаемым и управляемым. Новичку важно научиться видеть в HTTP-методе не “техническую деталь”, а механизм, который заранее снижает риск архитектурных ошибок.
Практический сценарий
Представим сервис заказов: пользователь нажимает кнопку оплаты, сеть на мгновение пропадает, клиент автоматически повторяет запрос. Если оплата сделана через незащищённый POST без политики идемпотентности, пользователь может получить двойное списание. Тот же сценарий, но с корректным методом и Idempotency-Key, завершится безопасно: сервер поймёт, что это повтор той же операции, и вернет прежний результат. Это хороший пример того, как правильная семантика HTTP напрямую влияет на деньги, доверие пользователей и нагрузку поддержки.