Методы API: GET, POST и другие запросы простыми словами

Веб-API работает по протоколу HTTP, и каждый запрос к нему сообщает серверу, какое действие нужно выполнить. Для этого существуют методы. Понимание методов помогает читать документацию API, обсуждать интеграции с разработчиками и понимать, почему некоторые операции можно безопасно повторять, а некоторые — нет.

Пять основных методов

GET — получить данные

Запрос на чтение: получить список заказов, карточку клиента, остатки товара. GET не должен ничего менять на сервере. Параметры обычно передаются в адресе: например, фильтр по дате или статусу. Поэтому через GET не передают пароли и чувствительные данные — адреса часто попадают в журналы и историю браузера.

POST — создать или выполнить действие

Создание нового ресурса: новый заказ, новая заявка, новый клиент. Данные передаются в теле запроса, обычно в формате JSON. POST также используют для действий, которые плохо укладываются в «создать/изменить»: отправить SMS, рассчитать доставку, запустить выгрузку.

PUT — заменить целиком

Полная замена ресурса: клиент отправляет все поля записи, и сервер сохраняет её именно в таком виде. Если какое-то поле не передано, оно может быть очищено. Поэтому PUT используют, когда клиент точно знает всю запись.

PATCH — изменить частично

Изменение отдельных полей: поменять статус заказа, обновить телефон клиента. Передаются только изменяемые поля. На практике для обновления данных PATCH удобнее и безопаснее, чем PUT.

DELETE — удалить

Удаление ресурса. В бизнес-системах «удаление» часто реализуют как пометку или архивирование, чтобы не потерять историю: удалённый товар должен остаться в старых заказах.

Пример на заказах

• GET /orders?status=new — список новых заказов
• GET /orders/1052 — один заказ
• POST /orders — создать заказ
• PATCH /orders/1052 — изменить статус или адрес
• DELETE /orders/1052 — отменить или удалить черновик
• POST /orders/1052/refund — действие возврата

Безопасные и идемпотентные методы

Безопасный метод ничего не меняет: GET. Идемпотентный метод даёт тот же результат при повторе: два одинаковых PUT или DELETE подряд оставят систему в том же состоянии, что и один. POST не идемпотентен: если запрос на создание заказа отправлен дважды из-за обрыва связи, может появиться два заказа.

Для бизнеса это важно. При оплатах и создании заказов используют ключ идемпотентности: клиент присылает уникальный идентификатор операции, и сервер не создаёт дубль при повторе. Если вы подключаете платёжный сервис или службу доставки, обратите внимание, как в их API решена эта проблема.

Коды ответов

Сервер отвечает не только данными, но и кодом статуса:

• 200 — успешно, 201 — ресурс создан
• 400 — ошибка в запросе: не заполнено поле, неверный формат
• 401 — нужна авторизация, 403 — нет прав
• 404 — ресурс не найден
• 409 — конфликт, например повторное создание
• 429 — слишком много запросов
• 500 и выше — ошибка на стороне сервера

Код позволяет программе понять, что делать: исправить данные, повторить позже или сообщить пользователю.

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

• Изменение данных через GET: поисковые роботы или предзагрузка браузера могут случайно выполнить действие
• Все операции через POST на один адрес с параметром «action»: такой API сложнее понимать и кэшировать
• Ответ 200 с текстом ошибки внутри: программа клиента считает запрос успешным
• Отсутствие защиты от повторов при создании заказов и платежей

Что спросить при интеграции

Какие методы поддерживает API и для каких ресурсов? Как защищены операции от повторов? Какие коды ошибок возвращаются и с каким описанием? Есть ли ограничения на частоту запросов? Ответы определяют, насколько надёжной будет интеграция.