В чем разница между POST, PUT и PATCH?

Разница между POST, PUT и PATCH в REST API

Эти три HTTP метода используются для изменения состояния ресурсов на сервере, но каждый имеет свою семантику и область применения.

POST — Создание нового ресурса

POST используется для создания нового ресурса на сервере. После выполнения запроса сервер создаёт новый ресурс и возвращает его идентификатор.

// Запрос
POST /api/users
Content-Type: application/json

{
  "name": "Alice",
  "email": "alice@example.com"
}

// Ответ (201 Created)
{
  "id": 123,
  "name": "Alice",
  "email": "alice@example.com",
  "createdAt": "2024-01-15T10:00:00Z"
}

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

• Идемпотентность: НЕ идемпотентен. Каждый вызов создаёт новый ресурс
• Повторяемость: Повторный вызов создаст еще один ресурс
• Безопасность: Изменяет состояние сервера
• Код ответа: Обычно 201 Created

// REST контроллер в Spring
@PostMapping("/users")
public ResponseEntity<User> createUser(@RequestBody User user) {
    User created = userService.create(user);
    return ResponseEntity.status(HttpStatus.CREATED).body(created);
}

PUT — Замена всего ресурса

PUT используется для полной замены существующего ресурса. Клиент отправляет полное представление ресурса, и сервер заменяет весь ресурс целиком.

// Запрос — замена всего пользователя
PUT /api/users/123
Content-Type: application/json

{
  "name": "Bob",
  "email": "bob@example.com",
  "phone": "+1234567890"
}

// Ответ (200 OK)
{
  "id": 123,
  "name": "Bob",
  "email": "bob@example.com",
  "phone": "+1234567890"
}

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

• Идемпотентность: ИДЕМПОТЕНТЕН. Повторный вызов с теми же данными не изменит состояние
• Повторяемость: Безопасно повторять
• Полнота: Требует полное представление ресурса
• Код ответа: 200 OK или 204 No Content

@PutMapping("/users/{id}")
public ResponseEntity<User> updateUser(
    @PathVariable Long id,
    @RequestBody User user) {
    User updated = userService.update(id, user);
    return ResponseEntity.ok(updated);
}

PATCH — Частичное изменение ресурса

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

// Запрос — изменение только email
PATCH /api/users/123
Content-Type: application/json

{
  "email": "newemail@example.com"
}

// Ответ (200 OK) — все поля сохранены
{
  "id": 123,
  "name": "Bob",
  "email": "newemail@example.com",
  "phone": "+1234567890"
}

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

• Идемпотентность: Может быть идемпотентен (зависит от реализации)
• Повторяемость: Обычно безопасно повторять
• Полнота: Отправляют только измененные поля
• Код ответа: 200 OK или 204 No Content

@PatchMapping("/users/{id}")
public ResponseEntity<User> partialUpdate(
    @PathVariable Long id,
    @RequestBody Map<String, Object> updates) {
    User updated = userService.partialUpdate(id, updates);
    return ResponseEntity.ok(updated);
}

Сравнительная таблица

Практические примеры

Создание пользователя (POST):

POST /api/v1/users
{
  "username": "john_doe",
  "password": "secure123",
  "email": "john@example.com"
}

Полное обновление пользователя (PUT):

PUT /api/v1/users/5
{
  "username": "john_updated",
  "password": "newsecure456",
  "email": "john.new@example.com",
  "role": "admin"
}
// Все поля перезаписаны

Частичное обновление (PATCH):

PATCH /api/v1/users/5
{
  "email": "john.another@example.com"
}
// Только email изменен, остальное осталось

Обработка ошибок

@PutMapping("/users/{id}")
public ResponseEntity<?> updateUser(
    @PathVariable Long id,
    @RequestBody User user) {
    try {
        User updated = userService.update(id, user);
        return ResponseEntity.ok(updated);
    } catch (ResourceNotFoundException e) {
        return ResponseEntity.notFound().build();  // 404
    }
}

@PatchMapping("/users/{id}")
public ResponseEntity<?> patchUser(
    @PathVariable Long id,
    @RequestBody Map<String, Object> patches) {
    try {
        User updated = userService.partialUpdate(id, patches);
        return ResponseEntity.ok(updated);
    } catch (ResourceNotFoundException e) {
        return ResponseEntity.notFound().build();  // 404
    }
}

Когда использовать каждый метод

POST:

• Создание нового ресурса
• Запуск действий (не все действия должны быть через GET)
• Когда URL еще не известен

PUT:

• Полная замена существующего ресурса
• Когда вы отправляете все поля
• Когда операция идемпотентна

PATCH:

• Частичное обновление ресурса
• Когда отправляете только измененные поля
• Более эффективен для больших объектов

Выводы

ПОST используется для создания новых ресурсов и не идемпотентен. PUT заменяет весь ресурс и идемпотентен. PATCH используется для частичного обновления и не требует отправку всех полей. Выбирайте метод, исходя из семантики вашего API и требований к идемпотентности. REST лучшие практики рекомендуют использовать PATCH для безопасного частичного обновления данных.