При розробці 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 може бути визначена як новий ресурс користувачем, сервер походження може створити ресурс за цією адресою.
Іншими словами, метод PUT використовується для оновлення всього ресурсу на сервері. Це робить PUT більш «повним» оновленням, яке часто використовується, коли необхідна повна заміна ресурсу.
Отже, PUT найбільше підходить для таких випадків:
- Оновлення повного ресурсу (наприклад, оновлення профілю користувача з усією новою інформацією).
- Заміна всього елемента чи запису.
- Коли ідентичність ресурсу чітко визначена, а його дані потребують повного оновлення.
I need the complete text to translate. "In systems like" appears to be incomplete. Could you please provide the full English phrase or sentence you'd like translated to Ukrainian? 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 та PATCH у REST API
У REST API ідемпотентність означає властивість операції, яка при повторенні багато разів з одними й тими ж вхідними даними дає однаковий результат. Це означає, що повторне надсилання одного й того ж запиту повинно мати однаковий ефект на сервері, незалежно від кількості виконань. Це важливо для забезпечення стабільності та передбачуваності в API. Але як це стосується різниці між PUT і PATCH у REST API?
Метод PUT та ідемпотентність
Метод PUT у REST API завжди є ідемпотентним, оскільки він призначений для заміни всього ресурсу за вказаним URI даними, наданими в запиті. Іншими словами, якщо ви виконаєте PUT запит кілька разів з одними й тими ж даними ресурсу, результат завжди буде однаковим.
Чому 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 може привести до різних результатів. Це порушило б властивість ідемпотентності.
Приклад неідемпотентного PATCH API REST:
| PATCH /counter/1{"increment": 1} |
Якщо ви будете повторювати цей PATCH запит, лічильник буде збільшуватися, даючи щоразу нові значення. Це не ідемпотентно, тому що результат змінюється з кожним застосуванням.
Тепер, коли ви знаєте основи, давайте розглянемо кілька прикладів сценаріїв, щоб краще зрозуміти різницю між PUT та PATCH в REST APIs.
Приклади сценаріїв: PUT та PATCH у REST API
Вийшовши за межі теорії, давайте порівняємо PUT та PATCH на прикладах, включаючи як ідемпотентні, так і неідемпотентні операції.
Сценарій 1: PUT запит – повна заміна ресурсу
Уявіть API кінцеву точку для управління товарами в електронному магазині. Вам потрібно оновити всі деталі товару, включно з назвою, ціною та описом. Це типовий приклад різниці між методами PUT та PATCH (HTTP), де PUT використовується для повної заміни ресурсу товару.
Початковий Продукт:
| GET /products/1001{"id": 1001,"name": "Laptop","price": 999.99,"description": "A powerful laptop."} |
Ви хочете оновити ціну та опис товару. Ви надсилаєте PUT запит з повним ресурсом:
PUT Request: 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 приклад API: якщо ви хочете змінити опис товару, але не його ціну, PATCH є кращим вибором. Для реалізації цього ви можете створити патчі, які містять лише поля, які потребують змін, такі як опис у цьому прикладі PATCH API REST.
Початковий Продукт:
| 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 запит кілька разів, опис залишиться незмінним після першого оновлення, що робить запит ідемпотентним.
Результат (після PATCH запиту):
| {"id": 1001,"name": "Laptop","price": 999.99,"description": "A lightweight, powerful laptop."} |
Якщо ви повторно застосуєте той самий PATCH, опис товару залишиться таким самим, як після першого PATCH. Результат є послідовним, що робить PATCH ідемпотентним у цьому сценарії.
Сценарій 3: PATCH запит – неідемпотентна операція
Давайте розглянемо неідемпотентну операцію PATCH. Припустимо, є кінцева точка для балансу гаманця користувача, і ви хочете збільшити баланс. Різниця між PUT та PATCH може бути проілюстрована тут: PATCH буде додавати значення до балансу щоразу
Початковий гаманець:
| GET /users/1/wallet{"id": 1,"balance": 100.00} |
Запит PATCH:
| PATCH /users/1/wallet{"increment": 50.00} |
Цей PATCH запит збільшить баланс гаманця на 50 доларів. Якщо ви надішлете цей PATCH запит кілька разів, баланс буде збільшуватися з кожним 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: якщо ви хочете оновити лише email користувача, патч надішле тільки поле email, на відміну від 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 vs оновлення REST) на основі вашого сценарію, ви зробите API більш ефективним, підтримуваним і зручним для користувача. Завжди враховуйте характер оновлення — повне це або часткове — а також вплив на продуктивність і цілісність даних, і виберіть метод, який найкраще відповідає вашим потребам.
