У дизайні RESTful API PUT і PATCH — це два HTTP-методи, які використовуються для оновлення ресурсів на сервері, але різниця між PUT і PATCH в REST API полягає в тому, як вони виконують оновлення та сценарії, у яких кожен з них найбільш прийнятний. Обидва методи призначені для зміни існуючих даних, але розуміння різниці PUT і PATCH в REST API може допомогти розробникам зробити найкращий вибір на основі характеру оновлення, яке їм потрібно виконати. У цьому дописі блогу ми дослідимо різницю між PUT і PATCH в REST API, зосередимося на дискусії PATCH проти оновлення 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, ідемпотентні операції необхідні для забезпечення узгодженості даних. Наприклад, оновлення документа в Elasticsearch за допомогою PUT гарантує, що той самий запит можна буде повторити без небажаних побічних ефектів.
Що таке PATCH в REST API?
Тепер, коли ми розглянули PUT в REST API, давайте розглянемо, що таке PATCH в REST API і як він працює, перш ніж порівнювати PUT з PATCH в REST API. Як визначено в RFC 5789, метод PATCH в REST API вимагає застосування набору змін, описаних в сутності запиту, до ресурсу, визначеного Request-URI.
Це узгоджується з різницею PUT проти PATCH REST API, коли ви надсилаєте лише дані, які потрібно змінити, а сервер застосовує ці зміни до наявного ресурсу, не змінюючи весь ресурс. Розробники часто створюють виправлення для відображення цих поступових змін, забезпечуючи мінімальну передачу даних і ефективні оновлення.
Ось чому метод 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”: “[email protected]”} |
Якщо ви надішлете цей запит кілька разів, результат завжди буде однаковим:
| {“ім’я користувача”: “john_doe”,”email”: “[email protected]”} |
Навіть якщо дані користувача вже є такими, повторна відправка запиту нічого не змінить. Він замінює дані тими самими даними, тому ефект запиту залишається незмінним незалежно від того, скільки разів він повторюється. Саме це робить PUT ідемпотентним.
Метод PATCH і ідемпотенція
З іншого боку, метод PATCH в REST API, як правило, також ідемпотентний, але з більшою гнучкістю. Коли ви створюєте патчі, переконайтеся, що операції є ідемпотентними (наприклад, встановлення значення), щоб уникнути небажаних побічних ефектів від повторних запитів. Чи є PATCH ідемпотентним, залежить від операції та даних, що змінюються.
Чому PATCH ідемпотентний? Для запитів PATCH ідемпотентність означає, що застосування того самого патча кілька разів матиме той самий результат. Це вірно, якщо сам пластир не викликає додаткових побічних ефектів або змін при повторному застосуванні. Якщо ви продовжуєте застосовувати той самий патч із тими самими даними, результат не зміниться після першого застосування.
Наприклад, якщо ви лише оновлюєте електронну пошту користувача, повторне надсилання того самого запиту PATCH не змінить результат після першого разу, навіть якщо запит зроблено кілька разів. Електронна пошта користувача залишиться незмінною, а стан ресурсу не зміниться.
Приклад PATCH API:
| ПАТЧ /users/1{“email”: “[email protected]”} |
Якщо адреса електронної пошти вже була [email protected], повторне застосування цього ПАТЧУ не призведе до змін, що зробить його ідемпотентним.
Однак у деяких випадках PATCH також може бути неідемпотентним. Наприклад, якщо операція PATCH змінює лічильник або додає елементи до списку (наприклад, збільшення числа або додавання до масиву), повторне застосування того самого PATCH може призвести до різних результатів. Це порушило б властивість ідемпотентності.
Приклад неідемпотентного патча API REST:
| PATCH /лічильник/1{“приріст”: 1} |
Якщо ви застосовуєте цей ПАТЧ неодноразово, лічильник буде постійно збільшуватися, що призведе до різних значень щоразу. Це не є ідемпотентним, оскільки результат змінюється з кожним застосуванням.
Тепер, коли ви знаєте основне, ми можемо розглянути кілька прикладів сценаріїв, щоб краще зрозуміти різницю між PUT і PATCH в REST API.
Приклади сценаріїв: PUT проти PATCH в REST API
Залишаючи теорію в стороні, давайте розглянемо різницю між PUT і PATCH на прикладах, включаючи як ідемпотентні, так і неідемпотентні операції.
Сценарій 1: запит PUT – заміна всього ресурсу
Уявіть собі кінцеву точку API для керування продуктами в системі електронної комерції. Вам потрібно оновити всі деталі продукту, включаючи його назву, ціну та опис. Це типовий приклад методу HTTP PUT проти PATCH, де PUT використовується для заміни повного ресурсу продукту.
Початковий продукт:
| GET /products/1001{“id”: 1001,”name”: “Laptop”,”price”: 999,99,”description”: “Потужний ноутбук.”} |
Ви хочете оновити ціну та опис товару. Ви надсилаєте запит PUT з усім ресурсом:
Запит PUT:
| PUT /products/1001{“id”: 1001,”name”: “Laptop”,”price”: 899,99,”description”: “Потужний ноутбук зі знижкою.”} |
Якщо ви зробите цей запит PUT один або кілька разів, результат завжди буде однаковим. Деталі продукту буде оновлено, щоб відобразити нову ціну та опис, і щоразу відбуватиметься той самий результат. Це забезпечує ідемпотентний характер PUT.
Результат (після запиту PUT):
| {“id”: 1001,”name”: “Laptop”,”price”: 899.99,”description”: “Потужний ноутбук зі знижкою.”} |
Сценарій 2: Запит на виправлення – оновлення частини ресурсу
Тепер давайте розглянемо запит PATCH для оновлення лише частини деталей продукту, наприклад опису. Приклад PATCH API: якщо ви хочете змінити опис продукту, але не його ціну, PATCH є кращим вибором. Щоб реалізувати це, вам слід створити патчі, що містять лише поля, які потребують модифікації, як-от опис у цьому прикладі API REST PATCH.
Початковий продукт:
| GET /products/1001{“id”: 1001,”name”: “Laptop”,”price”: 999,99,”description”: “Потужний ноутбук.”} |
Запит на ПАТЧ:
| ПАТЧ /products/1001{“опис”: “Легкий, потужний ноутбук.”} |
Коли ви надсилаєте цей запит PATCH, буде оновлено лише поле опису. Якщо ви надсилаєте той самий запит PATCH кілька разів, опис залишиться незмінним після першого оновлення, що робить запит ідемпотентним.
Результат (після запиту PATCH):
| {“id”: 1001,”name”: “Laptop”,”price”: 999,99,”description”: “Легкий, потужний ноутбук.”} |
Якщо ви знову застосувате той самий ПАТЧ, опис продукту залишиться таким самим, як і після першого ПАТЧУ. Результат узгоджений, що робить PATCH ідемпотентним у цьому сценарії.
Сценарій 3: Запит на ПАТЧ – неідемпотентна операція
Давайте розглянемо неідемпотентну операцію PATCH. Припустімо, що є кінцева точка для балансу гаманця користувача, і ви хочете збільшити баланс. Приклад різниці між PUT і PATCH можна проілюструвати тут: PATCH додаватиме значення до балансу щоразу
Початковий гаманець:
| ОТРИМАЙТЕ /users/1/wallet{“id”: 1,”balance”: 100.00} |
Запит на ПАТЧ:
| ПАТЧ /users/1/wallet{“приріст”: 50,00} |
Цей запит PATCH збільшить баланс гаманця на $50. Якщо ви надішлете цей запит PATCH кілька разів, баланс буде збільшуватися з кожним PATCH, що призведе до іншого результату щоразу. Це неідемпотентно, тому що повторне застосування того самого ПАТЧУ призведе до іншого результату.
Результат (після першого запиту PATCH):
| {“id”: 1,”balance”: 150.00} |
Результат (після другого запиту PATCH):
| {“id”: 1,”balance”: 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 ефективнішим, зручнішим у обслуговуванні та зручнішим для користувача. Завжди враховуйте характер оновлення — повне чи часткове — разом із впливом на продуктивність і цілісність даних і виберіть метод, який найкраще відповідає вашим потребам.
