В RESTful API дизайне PUT и PATCH — это два метода HTTP, используемых для обновления ресурсов на сервере, но разница между PUT и PATCH в REST API заключается в том, как именно они выполняют обновления и в каких сценариях каждый из них наиболее уместен. Оба метода предназначены для изменения существующих данных, однако понимание разницы между PUT и PATCH в REST API помогает разработчикам сделать правильный выбор в зависимости от характера нужного обновления. В этой статье мы разберём разницу между PUT и PATCH в REST API, рассмотрим дискуссию PATCH vs update REST, объясним, когда использовать каждый метод, и поможем выбрать подходящий вариант для разных сценариев.
Что такое PUT в REST API?
Чтобы понять разницу между PUT и PATCH в REST APIs, сначала разберёмся, что такое PUT. Согласно Раздел 9.6 RFC 2616, метод PUT в REST API запросах указывает, что переданная сущность должна быть сохранена по указанному Request-URI.
Если Request-URI указывает на уже существующий ресурс, переданная сущность ДОЛЖНА рассматриваться как обновлённая версия ресурса на исходном сервере. Если Request-URI не указывает на существующий ресурс, но этот URI может быть определён как новый ресурс запрашивающим агентом, исходный сервер вправе создать ресурс по этому URI.
Иными словами, метод PUT используется для полного обновления ресурса на сервере. Это делает PUT «полным» обновлением — он применяется, когда ресурс нужно заменить целиком.
PUT лучше всего подходит для следующих случаев:
- Полное обновление ресурса (например, обновление профиля пользователя с полным набором новых данных).
- Замена целого объекта или записи.
- Когда идентификатор ресурса известен и его данные нужно обновить полностью.
В таких системах, как Elasticsearch, идемпотентные операции необходимы для обеспечения согласованности данных. Например, обновление документа в Elasticsearch с помощью PUT гарантирует, что повторные запросы не вызовут непредвиденных побочных эффектов.
Что такое PATCH в REST API?
Теперь, разобравшись с PUT в REST APIs, давайте рассмотрим, что такое PATCH в REST APIs и как он работает, прежде чем сравнивать PUT и PATCH в REST APIs. Согласно RFC 5789, метод PATCH в REST API запросах применяет набор изменений, описанных в теле запроса, к ресурсу, идентифицированному по Request-URI.
Это отражает суть различия PUT и PATCH в REST API: вы передаёте только те данные, которые нужно изменить, а сервер применяет эти изменения к существующему ресурсу, не затрагивая его остальную часть. Разработчики часто формируют патчи для таких инкрементальных изменений, что минимизирует объём передаваемых данных и повышает эффективность обновлений.
Именно поэтому метод PATCH в REST API лучше подходит для следующих случаев:
- Обновление только части полей ресурса (например, изменение email-адреса или номера телефона пользователя). Пример PATCH API — отправка только нового email без изменения остальных полей.
- Снижение нагрузки за счёт уменьшения объёма передаваемых данных.
- Когда ресурс нужно обновить частично, а не заменять целиком.
- Формируйте патчи для точечных изменений отдельных полей, например изменения email пользователя, не затрагивая несвязанные данные.
Для таких платформ, как безголовая CMS которые нередко работают со сложными структурами контента, применение PATCH для небольших обновлений — например, изменения одного поля — снижает нагрузку на сервер и повышает производительность.
Разобравшись с обоими методами, вы уже должны понимать, что такое PUT и PATCH в REST API. Но прежде чем перейти к различиям между PUT и PATCH в REST API, нужно поговорить об идемпотентности этих двух методов.
Идемпотентность в PUT и PATCH в REST API
В контексте REST API идемпотентность означает свойство операции, при котором её повторное выполнение с теми же входными данными всегда даёт одинаковый результат. Иными словами, сколько бы раз вы ни отправили один и тот же запрос, эффект на стороне сервера будет одинаковым. Это важно для обеспечения стабильности и предсказуемости API. Но как это связано с разницей между PUT и PATCH в REST API?
Метод PUT и идемпотентность
Метод PUT в REST API всегда идемпотентен, поскольку он предназначен для полной замены ресурса по указанному URI данными из запроса. Другими словами, если вы выполните PUT-запрос несколько раз с одними и теми же данными ресурса, результат будет одинаковым.
Почему PUT идемпотентен? Отправляя PUT-запрос, вы фактически сообщаете серверу: «Вот именно то состояние, которое должен иметь этот ресурс». Неважно, отправите вы запрос один раз или десять: итоговый ресурс будет одинаковым.
Например, представьте, что вы обновляете адрес электронной почты пользователя. Если отправить один и тот же PUT-запрос несколько раз, результат не изменится, поскольку каждый раз ресурс заменяется теми же данными.
Пример:
| PUT /users/1{"username": "john_doe","email": "[email protected]"} |
Сколько бы раз вы ни отправили этот запрос, результат будет одинаковым:
| {"username": "john_doe","email": "[email protected]"} |
Даже если данные пользователя уже соответствуют этим значениям, повторная отправка запроса ничего не изменит. Данные просто заменяются теми же данными, поэтому эффект остаётся одинаковым независимо от количества повторений. Именно это делает PUT идемпотентным.
Метод PATCH и идемпотентность
Метод PATCH в REST API также, как правило, идемпотентен, но обладает большей гибкостью. При создании патчей убедитесь, что операции идемпотентны (например, установка конкретного значения), чтобы избежать нежелательных побочных эффектов при повторных запросах. Идемпотентность PATCH зависит от конкретной операции и изменяемых данных.
Почему PATCH идемпотентен? Применительно к PATCH-запросам идемпотентность означает, что многократное применение одного и того же патча даёт одинаковый результат. Это справедливо до тех пор, пока патч не вызывает дополнительных побочных эффектов при повторном применении. Если раз за разом применять один и тот же патч с теми же данными, состояние ресурса после первого применения меняться не должно.
Например, если вы обновляете только адрес электронной почты пользователя, повторная отправка одного и того же PATCH-запроса не изменит результат после первого применения, сколько бы раз запрос ни был отправлен. Адрес почты останется прежним, и состояние ресурса не изменится.
Пример PATCH API:
| PATCH /users/1{"email": "[email protected]"} |
Если адрес почты уже был [email protected], повторное применение этого PATCH не изменит ничего — запрос остаётся идемпотентным.
Однако в ряде случаев PATCH может быть неидемпотентным. Например, если PATCH-операция изменяет счётчик или добавляет элементы в список (скажем, увеличивает число или дописывает элемент в массив), каждое повторное применение одного и того же PATCH будет давать разный результат. Это нарушает свойство идемпотентности.
Пример неидемпотентного API REST PATCH:
| PATCH /counter/1{"increment": 1} |
При каждом применении этого PATCH счётчик будет увеличиваться, и результат будет отличаться. Это неидемпотентная операция, поскольку результат меняется с каждым применением.
Теперь, когда вы знаете основы, разберём несколько практических сценариев, которые помогут лучше понять разницу между PUT и PATCH в REST API.
Примеры сценариев: PUT vs PATCH в REST API
Отложим теорию в сторону и рассмотрим разницу между PUT и PATCH на конкретных примерах, включая как идемпотентные, так и неидемпотентные операции.
Сценарий 1: PUT-запрос — полная замена ресурса
Представьте API-эндпоинт для управления товарами в интернет-магазине. Вам нужно обновить все данные товара: название, цену и описание. Это типичный пример выбора между HTTP методами PUT и PATCH, где PUT используется для полной замены ресурса товара.
Исходный товар:
| GET /products/1001{"id": 1001,"name": "Laptop","price": 999.99,"description": "A powerful laptop."} |
Вы хотите обновить цену и описание товара. Для этого отправьте PUT-запрос с полным представлением ресурса:
PUT-запрос:
| PUT /products/1001{"id": 1001,"name": "Laptop","price": 899.99,"description": "A discounted powerful laptop."} |
Неважно, сколько раз вы отправите этот PUT-запрос — результат всегда будет одинаковым. Данные товара обновятся до указанных значений цены и описания, и каждый повторный запрос даст тот же результат. Именно это делает PUT идемпотентным.
Результат (после PUT-запроса):
| {"id": 1001,"name": "Laptop","price": 899.99,"description": "A discounted powerful laptop."} |
Сценарий 2: PATCH-запрос — частичное обновление ресурса
Теперь рассмотрим PATCH-запрос для обновления только части данных товара — например, описания. Если нужно изменить описание, не затрагивая цену, PATCH — правильный выбор. В теле запроса передаются только те поля, которые требуют изменения, например описание.
Исходный товар:
| GET /products/1001{"id": 1001,"name": "Laptop","price": 999.99,"description": "A powerful laptop."} |
PATCH-запрос:
| PATCH /products/1001{"description": "A lightweight, powerful laptop."} |
При отправке этого PATCH-запроса обновится только поле описания. Если отправить тот же запрос несколько раз, описание останется неизменным после первого обновления — это делает запрос идемпотентным.
Результат (после PATCH-запроса):
| {"id": 1001,"name": "Laptop","price": 999.99,"description": "A lightweight, powerful laptop."} |
Если применить тот же PATCH повторно, описание товара останется таким же, как после первого запроса. Результат стабилен — именно поэтому PATCH идемпотентен в данном сценарии.
Сценарий 3: PATCH-запрос — неидемпотентная операция
Рассмотрим неидемпотентный PATCH-запрос. Допустим, есть эндпоинт для баланса кошелька пользователя, и вы хотите его пополнить. Каждый PATCH-запрос будет прибавлять указанную сумму к текущему балансу.
Исходное состояние кошелька:
| GET /users/1/wallet{"id": 1,"balance": 100.00} |
PATCH-запрос:
| PATCH /users/1/wallet{"increment": 50.00} |
Этот PATCH-запрос увеличит баланс кошелька на $50. При каждой повторной отправке баланс будет продолжать расти, и результат каждый раз будет отличаться. Операция неидемпотентна: один и тот же запрос даёт разный результат в зависимости от того, сколько раз он был выполнен.
Результат (после первого PATCH-запроса):
| {"id": 1,"balance": 150.00} |
Результат (после второго PATCH-запроса):
| {"id": 1,"balance": 200.00} |
В этом примере PATCH не является идемпотентным: одни и те же данные в запросе приводят к разным результатам при каждом повторном вызове.
Итог: ключевые различия между PUT и PATCH в REST APIs
Ключевое различие между PUT и PATCH в REST API — в том, как они обрабатывают обновления. PUT полностью заменяет ресурс: любые отсутствующие поля будут удалены, что может привести к потере данных. Именно поэтому разработчики используют PATCH для частичных обновлений — чтобы не затирать неизменённые поля и сохранять целостность данных.
Это делает PATCH эффективнее для частичных обновлений. Пример PATCH API: если нужно обновить только email пользователя, PATCH отправит только это поле. PUT в той же ситуации потребует передать все данные пользователя целиком.
PUT требует передачи полного набора данных. Каждое поле должно быть отправлено — отсутствующие поля будут стёрты. PATCH, напротив, передаёт только те поля, которые нужно изменить. Это особенно удобно для больших ресурсов с минимальными изменениями. Метод PATCH в REST API позволяет делать точечные, компактные запросы и снижает объём передаваемых данных.
PUT и PATCH — оба идемпотентны. Это означает, что повторный вызов того же запроса даёт тот же результат. Однако PUT предсказуемее: он каждый раз заменяет ресурс целиком. PATCH, обновляя только указанные поля, может давать разные результаты в зависимости от того, как сервер обрабатывает обновления.
Например, если PATCH увеличивает счётчик, повторные запросы будут давать разные значения. Тем не менее операции PATCH API можно спроектировать так, чтобы они тоже были идемпотентными.
Итак, разница между PUT и PATCH в REST API сводится к характеру обновления: PATCH — для частичных изменений, PUT — для полной замены ресурса. Оба метода идемпотентны, но PATCH устроен сложнее.
Заключение
PUT и PATCH — оба базовых метода HTTP в REST API, но решают разные задачи. Это и есть суть различия между PUT и PATCH в REST API. Понимая разницу между PUT и PATCH на разобранных выше примерах, вы сможете заметно повысить эффективность, читаемость и функциональность своего API. Выбирая правильный метод (PATCH или REST-обновление) под конкретный сценарий, вы делаете API эффективнее, проще в поддержке и удобнее для пользователей. Всегда учитывайте характер обновления — полное оно или частичное — его влияние на производительность и целостность данных, и выбирайте метод, который подходит именно вашей задаче.
