Какие операции можно сделать методом POST?

Операции методом POST

POST — один из основных HTTP методов в REST API, предназначенный для создания ресурсов и выполнения операций с побочными эффектами. Рассмотрю различные типы операций, которые целесообразно реализовывать через POST.

1. Создание новых ресурсов (Create)

Основное назначение POST — создание нового объекта на сервере.

Примеры:

• POST /api/users — создание нового пользователя
• POST /api/products — добавление нового товара
• POST /api/orders — оформление заказа
• POST /api/comments — добавление комментария

Характеристики:

• Данные передаются в теле запроса (body)
• Сервер генерирует ID нового ресурса
• Возвращает 201 Created с данными созданного объекта
• Не идемпотентен (повторные запросы создают дубли)

2. Выполнение действий (Actions)

POST используется для операций, которые нельзя выразить как простое создание:

Операции обработки:

• POST /api/documents/{id}/convert — конвертация документа
• POST /api/images/{id}/resize — изменение размера изображения
• POST /api/reports/generate — генерация отчёта

Операции над статусом:

• POST /api/orders/{id}/confirm — подтверждение заказа
• POST /api/tasks/{id}/complete — завершение задачи
• POST /api/applications/{id}/approve — одобрение заявки

Операции взаимодействия:

• POST /api/users/{id}/follow — подписка на пользователя
• POST /api/posts/{id}/like — лайк поста
• POST /api/comments/{id}/share — поделиться комментарием

3. Отправка данных для обработки

Авторизация и аутентификация:

• POST /api/auth/login — вход в систему
• POST /api/auth/logout — выход из системы
• POST /api/auth/refresh-token — обновление токена
• POST /api/auth/register — регистрация нового пользователя

Отправка уведомлений:

• POST /api/messages/send — отправка сообщения
• POST /api/notifications/send — отправка уведомления
• POST /api/emails/send — отправка письма

Платежи и финансовые операции:

• POST /api/payments/process — обработка платежа
• POST /api/invoices/create — создание счёта
• POST /api/refunds/request — запрос возврата

4. Операции поиска и фильтрации (Search)

В некоторых случаях используют POST вместо GET для сложных фильтров:

• POST /api/products/search — поиск с множественными параметрами
• POST /api/transactions/filter — фильтрация по сложным критериям
• POST /api/users/export — экспорт отфильтрованного списка

Почему POST вместо GET:

• Много параметров фильтрации (GET имеет ограничение на длину URL)
• Сложные условия поиска
• Конфиденциальные данные в фильтрах

5. Загрузка файлов

• POST /api/files/upload — загрузка файла на сервер
• POST /api/images/upload — загрузка изображения
• POST /api/documents/upload — загрузка документа

Особенность: данные кодируются как multipart/form-data

6. Массовые операции (Bulk Operations)

• POST /api/users/bulk-create — создание множества пользователей
• POST /api/products/bulk-update — массовое обновление товаров
• POST /api/items/bulk-delete — массовое удаление записей

7. Запуск долгоживущих процессов

• POST /api/exports/start — запуск экспорта данных
• POST /api/backups/create — инициирование резервной копии
• POST /api/batch-jobs/queue — добавление задачи в очередь

Ответ возвращает ID задачи, который можно использовать для отслеживания статуса.

REST Best Practices для POST

Правильная структура:

POST /api/v1/resources
Content-Type: application/json

{
  "field1": "value1",
  "field2": "value2"
}

Ответ: 201 Created
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "field1": "value1",
  "field2": "value2",
  "created_at": "2026-03-26T10:30:00Z"
}

Таблица: POST vs другие методы

Ключевые принципы

• POST предназначен для побочных эффектов (изменение состояния сервера)
• Не идемпотентен — повторение может изменить результат
• Используй правильные коды ответов: 201 для создания, 200 для успешных операций
• Всегда возвращай новое состояние объекта в ответе
• Планируй обработку дублей (idempotency key) для критичных операций