В дизайне RESTful API PUT и PATCH — это два метода HTTP, используемые для обновления ресурсов на сервере, но разница между PUT и PATCH в REST API заключается в том, как они выполняют обновления, и в сценариях, в которых каждый из них наиболее подходит. Оба метода предназначены для изменения существующих данных, но понимание разницы PUT и PATCH в REST API может помочь разработчикам сделать лучший выбор в зависимости от характера обновления, которое им необходимо выполнить. В этом сообщении блога мы рассмотрим разницу PUT и PATCH в REST API, сосредоточив внимание на дебатах PATCH и update REST, когда использовать каждый из них, а также предоставим рекомендации по выбору правильного метода для разных случаев использования.
Что такое PUT в REST API?
Чтобы понять разницу между PUT и PATCH в REST API, сначала нам нужно знать, что такое PUT. На основе Раздел 9.6 RFC 2616, метод PUT в REST API запрашивает сохранение вложенного объекта под предоставленным Request-URI.
Если Request-URI ссылается на уже существующий ресурс, вложенный объект СЛЕДУЕТ рассматривать как модифицированную версию объекта, находящегося на исходном сервере. Если Request-URI не указывает на существующий ресурс и этот URI может быть определен как новый ресурс запрашивающим пользовательским агентом, исходный сервер может создать ресурс с этим URI.
Другими словами, метод PUT используется для обновления всего ресурса на сервере. Это делает PUT более «полным» обновлением, часто используемым, когда необходима полная замена ресурса.
Итак, PUT лучше всего подходит для следующих случаев использования:
- Обновление всего ресурса (например, обновление профиля пользователя всей новой информацией).
- Замена всего элемента или записи.
- Когда идентичность ресурса ясна и его данные необходимо полностью обновить.
В таких системах, как Эластичный поискидемпотентные операции необходимы для обеспечения согласованности данных. Например, обновление документа в Elasticsearch с помощью PUT гарантирует, что один и тот же запрос можно будет повторить без непредвиденных побочных эффектов.
Что такое PATCH в REST API?
Теперь, когда мы рассмотрели PUT в REST API, давайте посмотрим, что такое PATCH в REST API и как он работает, прежде чем сравнивать PUT и PATCH в REST API. Как определено в RFC 5789, метод PATCH в REST API запрашивает, чтобы набор изменений, описанных в объекте запроса, был применен к ресурсу, указанному Request-URI.
Это соответствует различию API PUT и PATCH REST, когда вы отправляете только те данные, которые необходимо изменить, а сервер применяет эти изменения к существующему ресурсу, не изменяя весь ресурс. Разработчики часто создают патчи для отражения этих дополнительных изменений, обеспечивая минимальную передачу данных и эффективные обновления.
Вот почему метод PATCH в REST API лучше подходит для следующих случаев использования:
- Обновление только подмножества полей ресурса (например, изменение адреса электронной почты или номера телефона пользователя). Пример PATCH API может включать отправку только нового электронного письма, оставляя другие поля нетронутыми.
- Повышение производительности за счет минимизации полезной нагрузки данных.
- Если вы хотите обновить ресурс постепенно, а не заменить его полностью.
- Создавайте патчи для инкапсуляции изменений определенных полей, например изменения электронной почты пользователя, не затрагивая несвязанные данные.
Для таких платформ, как безголовая CMS которые часто обрабатывают сложные структуры контента, использование PATCH для небольших обновлений (например, изменения одного поля) может снизить нагрузку на сервер и повысить производительность.
Изучив эти два метода, вы должны иметь хорошее представление о том, что такое PUT и PATCH в REST API. Однако, прежде чем мы углубимся в разницу между PUT и PATCH в REST API, нам нужно поговорить об идемпотентности в этих двух методах.
Идемпотентность в PUT и патче в REST API
В REST API идемпотентность относится к свойству операции, которая при многократном повторении с одними и теми же входными данными приводит к одному и тому же результату. Это означает, что выполнение одного и того же запроса несколько раз должно иметь одинаковый эффект на сервере, независимо от того, сколько раз он выполнялся. Это важно для обеспечения стабильности и предсказуемости API. Но какое отношение это имеет к разнице PUT и PATCH в REST API?
Метод PUT и идемпотентность
Метод PUT в REST API всегда идемпотентен, поскольку он предназначен для замены всего ресурса по указанному URI данными, предоставленными в запросе. Другими словами, если вы выполняете запрос PUT несколько раз с одними и теми же данными ресурса, результат всегда будет одинаковым.
Почему PUT идемпотентен? Когда вы делаете запрос PUT, вы, по сути, сообщаете серверу: «Это полное и точное состояние, которое я хочу для этого ресурса». Независимо от того, выполняете ли вы запрос PUT один или несколько раз, результирующий ресурс всегда будет идентичен.
Например, рассмотрим сценарий, в котором вы обновляете адрес электронной почты пользователя. Если вы сделаете один и тот же запрос PUT несколько раз, результат не изменится, поскольку ресурс каждый раз заменяется одними и теми же данными.
Пример:
| PUT /users/1{"имя пользователя": "john_doe","электронная почта": "[email protected]"} |
Если вы отправите этот запрос несколько раз, результат всегда будет одинаковым:
| {«имя пользователя»: «john_doe», «электронная почта»: «[email protected]»} |
Даже если данные пользователя уже такие, повторная отправка запроса ничего не меняет. Он заменяет данные теми же данными, поэтому эффект запроса остается неизменным независимо от того, сколько раз он повторяется. Именно это делает PUT идемпотентным.
Метод PATCH и идемпотентность
С другой стороны, метод PATCH в REST API, как правило, также идемпотентен, но обладает большей гибкостью. При создании исправлений убедитесь, что операции идемпотентны (например, установка значения), чтобы избежать непредвиденных побочных эффектов от повторных запросов. Является ли PATCH идемпотентным, зависит от операции и изменяемых данных.
Почему PATCH идемпотентен? Для запросов PATCH идемпотентность означает, что многократное применение одного и того же исправления приведет к одному и тому же результату. Это верно до тех пор, пока сам патч не вызывает дополнительных побочных эффектов или изменений при повторном применении. Если вы продолжаете применять один и тот же патч с теми же данными, результат не должен измениться после первого применения.
Например, если вы обновляете только электронную почту пользователя, повторная отправка одного и того же запроса PATCH не изменит результат после первого раза, даже если запрос будет сделан несколько раз. Электронная почта пользователя останется прежней, а состояние ресурса не изменится.
Пример API-ИСПРАВЛЕНИЯ:
| ПАТЧ /users/1{“электронная почта”: “[email protected]”} |
Если адрес электронной почты уже был [email protected], то повторное применение этого ИСПРАВЛЕНИЯ не приведет к каким-либо изменениям, что сделает его идемпотентным.
Однако в некоторых случаях PATCH может быть и неидемпотентным. Например, если операция PATCH изменяет счетчик или добавляет элементы в список (например, увеличивает число или добавляет к массиву), повторное применение одного и того же PATCH может привести к разным результатам. Это нарушило бы свойство идемпотентности.
Пример неидемпотентного API REST PATCH:
| ПАТЧ /counter/1{“приращение”: 1} |
Если вы примените этот PATCH повторно, счетчик будет продолжать увеличиваться, каждый раз приводя к разным значениям. Это не идемпотентно, поскольку результат меняется при каждом приложении.
Теперь, когда вы знаете основы, мы можем рассмотреть несколько примеров сценариев, чтобы лучше понять разницу между PUT и PATCH в REST API.
Примеры сценариев: PUT и PATCH в REST API
Оставляя в стороне теорию, давайте рассмотрим разницу между PUT и PATCH на примерах, включая как идемпотентные, так и неидемпотентные операции.
Сценарий 1. Запрос PUT — замена всего ресурса
Представьте себе конечную точку API для управления продуктами в системе электронной коммерции. Вам необходимо обновить все сведения о продукте, включая его название, цену и описание. Это типичный пример HTTP-метода PUT и PATCH, где PUT используется для замены полного ресурса продукта.
Исходный продукт:
| GET /products/1001{“id”: 1001”,name”: “Ноутбук”,”price”: 999,99,”description”: “Мощный ноутбук.”} |
Вы хотите обновить цену и описание продукта. Вы отправляете запрос PUT со всем ресурсом:
PUT-запрос:
| PUT /products/1001{“id”: 1001,name”: “Ноутбук”,”price”: 899,99,”description”: “Мощный ноутбук со скидкой.”} |
Если вы сделаете этот запрос PUT один или несколько раз, результат всегда будет одинаковым. Сведения о продукте будут обновлены с учетом новой цены и описания, и каждый раз будет происходить один и тот же результат. Это обеспечивает идемпотентную природу PUT.
Результат (после запроса PUT):
| {“id”: 1001, “name”: “Ноутбук”, “цена”: 899,99, “description”: “Мощный ноутбук со скидкой.”} |
Сценарий 2: Запрос PATCH — обновление части ресурса
Теперь давайте рассмотрим запрос PATCH для обновления только части сведений о продукте, например описания. Пример PATCH API: если вы хотите изменить описание продукта, но не его цену, PATCH — лучший выбор. Чтобы реализовать это, вы должны создать исправления, содержащие только поля, требующие изменения, такие как описание в этом примере API REST PATCH.
Исходный продукт:
| GET /products/1001{“id”: 1001”,name”: “Ноутбук”,”price”: 999,99,”description”: “Мощный ноутбук.”} |
Запрос на исправление:
| ПАТЧ /products/1001{"description": «Легкий и мощный ноутбук».} |
Когда вы отправляете этот запрос PATCH, будет обновлено только поле описания. Если вы отправите один и тот же запрос PATCH несколько раз, описание останется неизменным после первого обновления, что сделает запрос идемпотентным.
Результат (после запроса PATCH):
| {“id”: 1001, “name”: “Ноутбук”, “цена”: 999,99, “description”: “Легкий и мощный ноутбук”.} |
Если вы снова примените тот же ИСПРАВЛЕНИЕ, описание продукта останется таким же, каким оно было после первого ИСПРАВЛЕНИЯ. Результат согласован, что делает PATCH идемпотентным в этом сценарии.
Сценарий 3: Запрос PATCH – неидемпотентная операция
Давайте посмотрим на неидемпотентную операцию PATCH. Предположим, существует конечная точка баланса кошелька пользователя, и вы хотите увеличить баланс. Пример разницы между PUT и PATCH можно проиллюстрировать здесь: PATCH каждый раз будет добавлять значение к балансу.
Начальный кошелек:
| GET /users/1/wallet{“id”: 1”,balance”: 100,00} |
Запрос на исправление:
| ПАТЧ /users/1/wallet{“приращение”: 50.00} |
Этот запрос PATCH увеличит баланс кошелька на 50 долларов. Если вы отправите этот запрос PATCH несколько раз, баланс будет увеличиваться с каждым PATCH, что каждый раз приведет к разным результатам. Это неидемпотентно, поскольку повторное применение одного и того же PATCH приведет к другому результату.
Результат (после первого запроса PATCH):
| {“id”: 1,баланс: 150,00} |
Результат (после второго запроса PATCH):
| {“id”: 1,баланс: 200,00} |
Здесь PATCH не идемпотентен, поскольку повторные запросы с одними и теми же данными дают разные результаты.
Резюме: ключевые различия между PUT и PATCH в REST API
Ключевое различие между PUT и PATCH в REST API заключается в том, как они обрабатывают обновления. PUT заменяет весь ресурс, поэтому все недостающие поля удаляются, что может привести к потере данных. Именно поэтому разработчики создают патчи для частичных обновлений — чтобы избежать перезаписи неизмененных полей и сохранить целостность данных.
Это делает PATCH более эффективным для частичных обновлений. Пример PATCH API: если вы хотите обновить только электронную почту пользователя, создание исправлений будет отправлять только поле электронной почты, в отличие от запроса 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. Вы можете значительно повысить эффективность, ясность и функциональность своего API, поняв разницу между PUT и PATCH на примерах, которые мы рассмотрели ранее в этой статье. Выбрав правильный метод (PATCH или обновление REST) в зависимости от вашего варианта использования, вы можете сделать свой API более эффективным, удобным в обслуживании и удобным для пользователя. Всегда учитывайте характер обновления (полное или частичное), а также влияние на производительность и целостность данных и выбирайте метод, который лучше всего соответствует вашим потребностям.
