У контексті REST API, коли багато ідентичних запитів має той самий ефект, що й один запит, тоді такий REST API називається ідемпотентним.
1. Ідемпотентні API
Коли ми розробляємо REST API, ми повинні усвідомлювати, що споживачі API можуть робити помилки. Споживачі можуть написати код клієнта таким чином, щоб до API могли надходити повторювані запити.
Ці повторювані запити можуть бути ненавмисними, а іноді й навмисними (наприклад, через тайм-аут або проблеми з мережею). Ми повинні зробити наші API стійкими до збоїв, щоб повторювані запити не залишали систему нестабільною.
Ідемпотентний метод HTTP — це метод, який можна викликати багато разів без різних результатів. Не повинно мати значення, чи був метод викликаний лише один раз чи десять разів. Результат завжди повинен бути однаковим.
Ідемпотентність по суті означає, що вплив успішно виконаного запиту на ресурс сервера не залежить від кількості його виконання.
Наприклад, в арифметиці додавання нуля до числа є ідемпотентною операцією.
2. Ідемпотентність з методами HTTP
Якщо ми дотримуємося принципів REST при розробці наших API, ми матимемо автоматично ідемпотентні API REST для методів GET, PUT, DELETE, HEAD, OPTIONS і TRACE. Тільки POST API не будуть ідемпотентними .
- POST – Не є ідемпотентним.
- GET, PUT, DELETE, HEAD, OPTIONS і TRACE – ідемпотентні.
Давайте проаналізуємо, як наведені вище методи HTTP виявляються ідемпотентними – і чому POST не є таким.
2.1. HTTP POST
Зазвичай (не обов’язково) POST API використовуються для створення нового ресурсу або об’єкту на сервері.
Отже, коли ми викликаємо той самий запит POST N разів, ми матимемо N нових ресурсів або об’єктів на сервері. Отже, POST не є ідемпотентним.
2.2. HTTP GET, HEAD, OPTIONS і TRACE
GET, HEAD, OPTIONS і TRACE методи НІКОЛИ не змінюють стан ресурсу на сервері бо не передають комплексних даних. Вони призначені виключно для отримання представлення ресурсу або метаданих у цей момент часу.
Таким чином, виклик кількох запитів не матиме жодної операції запису на сервері, тому GET, HEAD, OPTIONS і TRACE є ідемпотентними.
2.3. HTTP PUT
Зазвичай (не обов’язково) PUT API використовуються для оновлення стану ресурсу. Якщо ви викликаєте PUT API N разів, найперший запит оновить ресурс; інші запити N-1 просто перезаписуватимуть той самий стан ресурсу знову і знову – фактично нічого не змінюючи.
Отже, PUT є ідемпотентним .
2.4 HTTP DELETE
2.4.1. Видалити згідно ідентифікатора ресурсу
Коли ви викликаєте N подібних DELETE запитів, перший запит видалить ресурс, а відповідь сервера буде 200 (OK) або 204 (No Content).
Інші запити N-1 повертатимуть 404 (не знайдено).
Зрозуміло, що відповідь відрізняється від першого запиту, але стан жодного ресурсу на стороні сервера не змінюється, оскільки вихідний ресурс уже видалено.
Отже, DELETE є ідемпотентним .
2.4.1. Видалення без ідентифікатора ресурсу
Будь ласка, майте на увазі, що деякі системи можуть мати такі API DELETE:
DELETE /item/last
У наведеному вище випадку виклик операції N раз видалить N ресурсів – отже DELETE, у цьому випадку не є ідемпотентним. У цьому випадку гарною пропозицією може бути зміна наведеного вище API на POST, оскільки POST не є ідемпотентним.
POST /item/last
Тепер це ближче до специфікації HTTP – отже, більш сумісно з REST.