API

HTTP-методи й ідемпотентність

HTTP-методи, ідемпотентність, PUT vs PATCH

Основні методи: GET — отримати ресурс, POST — створити, PUT — повністю замінити, PATCH — частково змінити, DELETE — видалити. Також HEAD повертає лише заголовки, а OPTIONS — дозволені методи, його використовує CORS preflight. Safe-методи не змінюють стан сервера: GET, HEAD, OPTIONS.

Ідемпотентний метод — коли кілька однакових запитів дають той самий стан сервера, що й один. GET, PUT і DELETE ідемпотентні, POST — ні: два POST створять два записи. Відповідь при цьому може відрізнятися, наприклад повторний DELETE поверне 404 замість 204.

PUT надсилає повне представлення ресурсу, і поля, яких немає в тілі, можуть бути скинуті. PATCH надсилає лише поля, що змінюються. PATCH не гарантовано ідемпотентний, наприклад операція «збільшити лічильник на 1». Це варто перевіряти в тестах: повторний PUT не повинен створювати дублікатів.

Таблиця методів

Ідемпотентний метод — це той, де повторний ідентичний запит не змінює стан сервера понад перший. Безпечний — той, що взагалі не змінює даних.

Метод	Для чого	Тіло	Ідемпотентний	Типовий успішний код
GET	Отримати ресурс або список	Ні	Так (і безпечний)	200
POST	Створити ресурс або виконати дію	Так	Ні	201
PUT	Замінити ресурс повністю	Так	Так	200 або 204
PATCH	Змінити окремі поля	Так	Не гарантовано	200
DELETE	Видалити ресурс	Зазвичай ні	Так	204 або 200
HEAD	Як GET, але лише заголовки	Ні	Так	200
OPTIONS	Які методи дозволені; CORS preflight	Ні	Так	204

Ідемпотентність стосується стану сервера, а не відповіді. Повторний DELETE може повернути 404 замість 204, але ресурс так само видалений — метод залишається ідемпотентним. HEAD корисний, коли треба перевірити наявність ресурсу чи розмір файлу без завантаження тіла.

На співбесіді: GET, PUT, DELETE, HEAD і OPTIONS ідемпотентні, POST — ні, а PATCH не гарантовано. Безпечні методи, як GET і HEAD, взагалі не змінюють даних.

PUT vs PATCH і Idempotency-Key у фінтеху

PUT vs PATCH. PUT надсилає весь об'єкт, і поле, яке ви не передали, може стати порожнім. PATCH змінює лише передані поля. Це готовий тест-кейс: зробити PUT без одного поля і перевірити через GET, що з ним сталося. Якщо поле стерлося, а в документації написано, що PUT — це повна заміна, то поведінка коректна; якщо ж API поводиться як PATCH, це розбіжність з контрактом.

Фінтех. POST неідемпотентний, тому повторне натискання «Сплатити» або повтор запиту після таймауту мережі може списати гроші двічі. Захист — заголовок Idempotency-Key: клієнт генерує унікальний ключ, сервер запам'ятовує його і на повтор повертає той самий результат, не створюючи другий платіж.

Як я це тестую:

Відправити POST /transfers з ключем K1, отримати 201 і id переказу.
Відправити той самий запит з тим самим K1.
Перевірити, що відповідь містить той самий id, а в базі чи історії транзакція одна.
Відправити інше тіло з тим самим K1 і перевірити, що сервер повертає помилку (часто 409 або 422), а не тихо виконує новий платіж.

На співбесіді: PUT замінює ресурс цілком, PATCH змінює лише передані поля, і я перевіряю це через GET після PUT без одного поля. Для платежів POST захищають Idempotency-Key, і я тестую, що повтор з тим самим ключем не створює другої транзакції.