Developer

Методы GET, POST, PUT, PATCH, DELETE

↑ 1.2 HTTP и REST для не-разработчиков · ← Предыдущая · → Следующая

Обязательно~7 мин чтенияУровень: junior

Зачем это аналитику и PM

Один и тот же адрес заказа может и показать карточку, и стереть её. Метод — это и есть выбор операции. Ошибка в методе превращает «повторить запрос» в второй платёж или в затирание полей.

План темы

  • что делает каждый
  • безопасные и идемпотентные методы
  • типичные ошибки выбора метода

Объяснение

Метод HTTP — глагол сообщения: что сделать с ресурсом, на который указывает адрес. Адрес говорит «какой заказ», метод говорит «прочитать, создать, заменить, поправить или удалить».

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

Что делает каждый

МетодОжиданиеМеняет данныеПовтор с теми же данными
GETПрочитатьНе долженТот же ответ, данных не прибавилось
POSTСоздать или запустить действиеДаМожет появиться вторая сущность
PUTЗаменить ресурс целикомДаИтог тот же, что после первого раза
PATCHИзменить часть полейДаСтандарт этого не обещает
DELETEУдалитьДаПовтор не должен удалить что-то ещё

GET используют для чтения списка и карточки. POST — для создания заказа и для действий, которые не укладываются в замену ресурса: «пересчитать», «отправить». PUT присылает полное новое состояние: поля, которых не было в теле, легко стереть. PATCH присылает только меняемые поля. DELETE убирает ресурс или помечает его удалённым. Как именно устроено удаление, пишут в контракте: мгновенное стирание и пометка «архив» для экрана выглядят похоже, а для отчёта нет.

Безопасный метод не меняет данные на сервере. Таким задуман GET. Идемпотентный метод можно повторить, и сверх первого раза итог не изменится. GET, PUT и DELETE задуманы идемпотентными. POST — нет. PATCH идемпотентен только если так гарантирует конкретное API, например когда вы шлёте целевые значения, а не команду «прибавь единицу».

flowchart TD
    A["Нужно назвать операцию"] --> B{"Данные меняются"}
    B -->|"нет, только чтение"| C["GET"]
    B -->|"да"| D{"Что именно меняется"}
    D -->|"новая сущность или действие"| E["POST"]
    D -->|"ресурс целиком"| F["PUT"]
    D -->|"часть полей"| G["PATCH"]
    D -->|"ресурс убирают"| H["DELETE"]

Если в спецификации чтение сделано методом POST, в задаче пишут факт контракта и отдельно помечают, что повтор опасен.

Типичные ошибки выбора

GET, который списывает деньги или ставит статус «прочитано» без оговорки, ломает ожидание безопасности: ссылку могут открыть префетчем, превью или повтором. POST «на всякий случай» для чтения отчёта мешает кэшу и делает повтор двусмысленным. PUT с двумя полями при ресурсе из двадцати затирает остальные восемнадцать. DELETE без описания повтора оставляет вопрос: второй вызов — это 404, тихий успех или ошибка «уже удалено». Для оплаты и создания заказа в требованиях нужна фраза, что будет при втором таком же запросе.

Примеры

Чтение учебного ресурса — GET без тела:

curl -sS "https://jsonplaceholder.typicode.com/posts/1"

Схема создания заказа. Это не живой магазин.

POST /orders HTTP/1.1
Host: api.example.com
Content-Type: application/json
 
{"sku": "MUG-1", "qty": 2}

Замена комментария целиком и точечная правка статуса — разные методы, даже если адрес один и тот же:

PUT /orders/1042 HTTP/1.1
Host: api.example.com
Content-Type: application/json
 
{"status": "packed", "comment": "хрупкое"}
PATCH /orders/1042 HTTP/1.1
Host: api.example.com
Content-Type: application/json
 
{"status": "packed"}

В схеме PUT тело обязано быть полным состоянием, которое команда считает «целым заказом».

Нюансы и подводные камни

  • Название метода в спецификации важнее учебника. Сначала читайте, что обещает ваш контракт при повторе.
  • «Идемпотентность» не значит «можно жать кнопку без последствий для человека». Два одинаковых PUT не создадут два заказа, но каждый вызов мог сдвинуть чужую интеграцию, если это не оговорено.
  • HEAD и OPTIONS тоже существуют. Для постановок аналитика они редки: HEAD просит заголовки без тела, OPTIONS спрашивает, какие методы разрешены.

Практика

Для действий «открыть карточку», «создать заказ», «сменить только комментарий», «отменить» выберите метод и одной фразой напишите, что делает повтор.

Ожидаемый результат: четыре строки. У создания сказано, что повтор может завести второй заказ, если нет отдельного ключа идемпотентности. У смены комментария видно, PUT это или PATCH, и не сотрутся ли другие поля.

Вопросы с ответами

Связано с блоком Developer

Связанные темы

Вид графа

Обратные ссылки