Когда используется тот или иной метод в REST?

Методы HTTP в RESTful API: стратегия выбора

В REST архитектуре HTTP методы (часто называемые глаголами) являются краеугольным камнем, определяющим семантику операции над ресурсом. Их корректное использование напрямую влияет на предсказуемость, безопасность и эффективность API. Вот детальное руководство по применению каждого метода.

Основные методы и их назначение

1. GET – Извлечение данных

Назначение: Запрос представления ресурса. Должен быть идемпотентным (повторные вызовы не изменяют состояние) и безопасным (не изменяет состояние сервера). Когда использовать:

• Получение списка сущностей (например, пользователей).
• Получение деталей конкретной сущности по ID.
• Поиск и фильтрация данных с использованием query-параметров. Ключевые аспекты:
• Не должен иметь тела запроса (payload).
• Данные передаются через URL и query-параметры.
• Результаты могут кэшироваться на всех уровнях.

GET /api/v1/users?active=true&role=admin HTTP/1.1
Host: example.com

2. POST – Создание нового ресурса

Назначение: Создание нового ресурса, идентификатор которого часто определяется сервером. Не является ни идемпотентным, ни безопасным. Когда использовать:

• Создание новой записи (пользователя, заказа, статьи).
• Отправка данных для обработки, когда результат не является простым созданием ресурса (например, запуск вычисления, конвертация файла).
• Выполнение сложных операций, не укладывающихся в CRUD-парадигму, через концепцию "контроллеров" (например, /batch-upload). Ключевые аспекты:
• Тело запроса содержит данные для создания.
• Успешный ответ – обычно 201 Created с заголовком Location, указывающим URI нового ресурса.

POST /api/v1/users HTTP/1.1
Host: example.com
Content-Type: application/json

{
  "name": "Иван Петров",
  "email": "ivan@example.com"
}

3. PUT – Полное обновление или создание

Назначение: Полная замена ресурса по известному URI. Идемпотентен. Если ресурс существует – он перезаписывается, если нет – может быть создан (хотя это поведение не всегда предпочтительно). Когда использовать:

• Обновление ВСЕХ полей существующего ресурса (например, профиля пользователя).
• Создание ресурса с заранее известным клиенту идентификатором (например, /configurations/main). Ключевые аспекты:
• Клиент должен передать полное представление ресурса.
• Отсутствующие поля могут быть интерпретированы как null.

PUT /api/v1/users/123 HTTP/1.1
Host: example.com
Content-Type: application/json

{
  "id": 123,
  "name": "Иван Петров (обновленный)",
  "email": "new-ivan@example.com",
  "status": "active"
}

4. PATCH – Частичное обновление

Назначение: Частичное изменение ресурса. Теоретически не идемпотентен, но на практике должен быть спроектирован как идемпотентный. Когда использовать:

• Обновление одного или нескольких полей ресурса без отправки всей сущности (например, изменение статуса заказа). Ключевые аспекты:
• Тело запроса содержит инструкции для изменения. Рекомендуется использовать стандартные форматы, такие как application/json-patch+json (RFC 6902) или application/merge-patch+json (RFC 7396).

PATCH /api/v1/users/123 HTTP/1.1
Host: example.com
Content-Type: application/json-patch+json

[
  { "op": "replace", "path": "/email", "value": "patched@example.com" }
]

5. DELETE – Удаление ресурса

Назначение: Удаление ресурса по указанному URI. Идемпотентен. Повторные вызовы должны возвращать тот же результат (404 Not Found или 410 Gone после первого успешного удаления). Когда использовать:

• Удаление конкретной сущности.
• Очистка коллекции (если поддерживается API дизайном, но с осторожностью). Ключевые аспекты:
• Успешный ответ – 200 OK (с телом), 202 Accepted (удаление поставлено в очередь) или 204 No Content.
• Тело запроса, как правило, не используется.

DELETE /api/v1/users/123 HTTP/1.1
Host: example.com

Реже используемые, но важные методы

• HEAD: Аналогичен GET, но сервер возвращает только заголовки (без тела). Используется для проверки существования ресурса, валидации по ETag или Last-Modified без передачи данных.
• OPTIONS: Описание возможных операций с ресурсом (доступные методы, CORS). Критически важен для безопасной работы браузерных клиентов.
• TRACE: Применяется для диагностики, возвращая клиенту полученный запрос. На практике почти не используется в публичных API из-за потенциальных уязвимостей.

Стратегические принципы выбора

1. Идемпотентность и безопасность: Это основа надежности. GET, HEAD, OPTIONS – безопасные. GET, PUT, DELETE, PATCH (спроектированный правильно) – идемпотентны. Это позволяет клиентам безопасно повторять запросы при сетевых сбоях.
2. Семантика над реализацией: Метод описывает что сделать, а не как. Сервер может выполнять сложную внутреннюю логику в ответ на POST, но с точки зрения клиента это единая операция создания.
3. Состояние ресурса: Методы оперируют ресурсами (существительные в URI), а не действиями (глаголы в URI). Вместо POST /calculateSalary используется POST /salary-calculations (создание ресурса "расчет").
4. Гипермедиа (HATEOAS): В идеальном REST ответы API содержат ссылки на возможные следующие действия, что частично снимает вопрос "какой метод использовать дальше" с клиента.

Пример дизайна для ресурса "Статья":

GET    /articles          -> Список статей
POST   /articles          -> Создать новую статью
GET    /articles/{id}     -> Получить статью
PUT    /articles/{id}     -> Полностью обновить статью
PATCH  /articles/{id}     -> Частично обновить статью (например, только title)
DELETE /articles/{id}     -> Удалить статью
POST   /articles/{id}/publish -> Контроллер-ресурс для действия "публикация"

Следование этим соглашениям создает самодокументированный, предсказуемый и легко интегрируемый API, что является одной из ключевых целей REST архитектуры. Для DevOps-инженера понимание этой семантики критически важно при проектировании CI/CD пайплайнов для тестирования API, настройке мониторинга (например, разный алерт на 5xx на GET и DELETE) и конфигурировании правил балансировки или кэширования (кэшируются в основном GET и HEAD).