PUT и PATCH запросы

В веб-разработке взаимодействие клиента и сервера строится на основе HTTP-запросов. Среди них особое место занимают методы PUT и PATCH, используемые для обновления данных на сервере. Хотя оба метода предназначены для изменения ресурсов, они имеют принципиальные различия, которые важно понимать при проектировании API и написании клиентского кода.

PUT: полное обновление ресурса

Метод PUT применяется для полного замещения существующего ресурса. При отправке PUT-запроса сервер ожидает, что в теле запроса будет представлен весь объект, который необходимо сохранить. Любые поля, отсутствующие в запросе, будут удалены или перезаписаны значениями по умолчанию на сервере.

Пример структуры PUT-запроса с использованием fetch:

fetch('https://api.example.com/users/123', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    id: 123,
    name: 'Иван Иванов',
    email: 'ivan@example.com'
  })
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Ошибка:', error));

Ключевые особенности PUT:

  • Требует полного объекта для обновления.
  • Идемпотентен: повторение запроса с одинаковыми данными не изменяет результат.
  • Используется для замены существующих ресурсов или их создания, если ресурс не существует (зависит от реализации сервера).

PATCH: частичное обновление ресурса

Метод PATCH предназначен для внесения частичных изменений в ресурс. В теле запроса можно передавать только те поля, которые необходимо изменить. Это делает PATCH более эффективным, особенно при работе с большими объектами или когда обновляются отдельные свойства.

Пример PATCH-запроса с fetch:

fetch('https://api.example.com/users/123', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'new_email@example.com'
  })
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Ошибка:', error));

Особенности PATCH:

  • Не требует полного объекта.
  • Модифицирует только указанные поля, оставляя остальные неизменными.
  • Обычно не идемпотентен по определению, но может быть реализован как идемпотентный.

Отличия PUT и PATCH

Характеристика PUT PATCH
Обновление Полное замещение ресурса Частичное изменение
Требование к данным Все поля ресурса Только изменяемые поля
Идемпотентность Да Обычно нет, зависит от реализации
Эффективность Ниже при больших объектах Выше при частичных изменениях

Использование в REST API

В REST API PUT часто используется для обновления сущности целиком, например, при редактировании профиля пользователя с передачей всех данных. PATCH подходит для сценариев, где необходимо изменить один или несколько атрибутов без пересылки всего объекта, например, изменение только адреса электронной почты или статуса заказа.

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

При использовании PUT и PATCH важно корректно обрабатывать ответы сервера и ошибки:

  • Проверка HTTP-кода ответа:

    • 200 OK — успешное обновление.
    • 201 Created — ресурс создан (для PUT при отсутствии ресурса).
    • 204 No Content — успешное обновление без возвращаемого тела.
    • 400 Bad Request — неверная структура запроса.
    • 404 Not Found — ресурс не найден.

  • Использование try/catch для обработки сетевых ошибок.

  • Валидация данных перед отправкой запроса для предотвращения ошибок на сервере.

Практические рекомендации

  • Использовать PUT для полного замещения ресурса, когда нужно гарантировать согласованность данных.
  • Использовать PATCH для оптимизации трафика и повышения производительности при частичных обновлениях.
  • Всегда явно указывать Content-Type: application/json при работе с JSON-данными.
  • Сохранять идемпотентность там, где это возможно, чтобы обеспечить предсказуемое поведение запросов.

PUT и PATCH являются фундаментальными инструментами для обновления ресурсов в современных веб-приложениях. Понимание их различий и правильное применение позволяет строить эффективные, масштабируемые и надежные RESTful API.

Оглавление