← Системный анализ: API, интеграции и данные
Урок
Методы HTTP: безопасность, идемпотентность, PUT против PATCH
Выбрать метод HTTP для операции по его свойствам — безопасный, идемпотентный — и объяснить на заказе разницу между POST, PUT и PATCH.
Что обещает каждый метод
Что обещает каждый метод
Безопасный метод не меняет состояние сервера: GET, HEAD, OPTIONS. Браузеры, прокси и поисковые роботы вправе повторять такие запросы и делать их заранее, про запас. Поэтому GET /orders/9001/cancel — ошибка проектирования: заказ отменится от случайного повтора.
Идемпотентный метод — такой, что повтор того же запроса оставляет сервер в том же состоянии, что и один запрос. Это GET, PUT, DELETE и все безопасные методы. Ответ на повтор может отличаться: второй DELETE может вернуть 404, но ресурс уже удалён — состояние то же.
• POST не идемпотентен: два POST /orders — два заказа.
• PATCH идемпотентность не гарантирует: «установить адрес» можно повторять, «увеличить количество на 1» — нет.
Зачем это аналитику: сеть рвётся, клиенты повторяют запросы. Идемпотентный запрос повторять безопасно, а для POST нужен ключ идемпотентности (юнит 4).
PUT заменяет ресурс целиком: чего нет в теле, то пропадёт, или сервер отклонит неполное тело. PATCH меняет только переданные поля: PATCH /orders/9001 с телом {"comment": "Позвонить у двери"} меняет один комментарий. В формате JSON Merge Patch (RFC 7396) значение null значит «удалить поле»: {"comment": null} стирает комментарий.
Отмена — не удаление: отменённый заказ остаётся в истории ради денег и отчётов. Встречаются два стиля — POST /orders/9001/cancel или PATCH со статусом cancelled (отменён). Выбирают один на весь API и фиксируют в контракте. DELETE /orders/9001 для отмены — ловушка.
Свойства методов
| Метод | Безопасный | Идемпотентный | В «Ромашке» |
|---|---|---|---|
| GET | да | да | получить заказ или список заказов |
| POST | нет | нет | создать заказ, отменить заказ |
| PUT | нет | да | сохранить адрес «дом» целиком: PUT /v1/customers/42/addresses/home |
| PATCH | нет | не гарантирован | изменить комментарий к заказу |
| DELETE | нет | да | удалить сохранённый адрес «дом» |
Конспект урока
Что обещает каждый метод
Безопасный метод не меняет состояние сервера: GET, HEAD, OPTIONS. Браузеры, прокси и поисковые роботы вправе повторять такие запросы и делать их заранее, про запас. Поэтому GET /orders/9001/cancel — ошибка проектирования: заказ отменится от случайного повтора.
Идемпотентный метод — такой, что повтор того же запроса оставляет сервер в том же состоянии, что и один запрос. Это GET, PUT, DELETE и все безопасные методы. Ответ на повтор может отличаться: второй DELETE может вернуть 404, но ресурс уже удалён — состояние то же.
• POST не идемпотентен: два POST /orders — два заказа.
• PATCH идемпотентность не гарантирует: «установить адрес» можно повторять, «увеличить количество на 1» — нет.
Зачем это аналитику: сеть рвётся, клиенты повторяют запросы. Идемпотентный запрос повторять безопасно, а для POST нужен ключ идемпотентности (юнит 4).
PUT заменяет ресурс целиком: чего нет в теле, то пропадёт, или сервер отклонит неполное тело. PATCH меняет только переданные поля: PATCH /orders/9001 с телом {"comment": "Позвонить у двери"} меняет один комментарий. В формате JSON Merge Patch (RFC 7396) значение null значит «удалить поле»: {"comment": null} стирает комментарий.
Отмена — не удаление: отменённый заказ остаётся в истории ради денег и отчётов. Встречаются два стиля — POST /orders/9001/cancel или PATCH со статусом cancelled (отменён). Выбирают один на весь API и фиксируют в контракте. DELETE /orders/9001 для отмены — ловушка.