REST API: проєктування
20 питань · ~20 хв · Версія v3.0
Увійдіть, щоб продовжити
Ресурси й методи HTTP, коди статусів, пагінація й фільтри, версіонування, ідемпотентність, контракт і документація - питання всіх рівнів, від junior до lead.
- За спробу
- 20
- У пулі
- 78
- Проходжень
- 0
- Середній бал
- -
- Пройшли на 70%+
- -
Питання для підготовки
36 питаньPOST- створити ресурс (або виконати дію). Сервер сам обирає адресу нового ресурсу:POST /orders→201 CreatedзLocation: /orders/42.PUT- замінити ресурс цілком тим, що в тілі запиту. Поля, яких немає в тілі, вважаються видаленими чи скинутими.PATCH- частково змінити ресурс: лише передані поля.
PUT /users/42
{"name": "Оля", "email": "olia@example.com", "phone": null}
PATCH /users/42
{"phone": "+380501234567"}
Ідемпотентність - ключова відмінність, про яку питають:
PUTіDELETEідемпотентні: повторний однаковий запит лишає ресурс у тому самому стані. Їх можна безпечно повторити при обриві з'єднання.POSTне ідемпотентний: повтор створить друге замовлення.PATCH- залежить від змісту: «встановити phone» ідемпотентний, «збільшити лічильник на 1» - ні.GET,HEAD,OPTIONS- ще й безпечні: не змінюють стан узагалі.
На практиці:
- Багато API використовують лише
PATCHдля оновлень, бо клієнту рідко потрібно надсилати весь ресурс. - Для створення з повторами (платежі)
POSTроблять ідемпотентним через заголовокIdempotency-Key. - Дії, що не вкладаються в CRUD (
/orders/42/cancel), зазвичай оформлюють якPOSTна під-ресурс.
Проблема: клієнт відправив POST /payments, а відповідь не дійшла - таймаут, обрив мережі. Чи пройшов платіж? Повторити запит небезпечно (подвійне списання), не повторити - теж (платіж може не пройти).
Рішення: клієнт генерує унікальний ключ (UUID) для кожної логічної операції і передає його в заголовку. Повтор з тим самим ключем не виконує операцію вдруге, а повертає збережену відповідь першого виконання.
POST /payments
Idempotency-Key: 4f0f9c2e-8b1a-4c3e-9d5f-2a7b6c8d9e01
{"amount": 5000, "currency": "UAH"}
Реалізація на сервері:
- Отримати ключ і атомарно зарезервувати його (унікальний індекс у таблиці чи
SET NXу Redis) разом з ID користувача. - Якщо ключ новий - виконати операцію й зберегти статус і тіло відповіді.
- Якщо ключ уже є й операція завершена - повернути збережену відповідь.
- Якщо ключ є, але операція ще виконується (паралельний повтор) -
409 Conflict, щоб клієнт повторив пізніше. - Якщо той самий ключ прийшов з іншим тілом запиту -
422: це помилка клієнта, ключ використано повторно для іншої операції.
Деталі, про які питають:
- Ключ прив'язують до користувача, щоб чужий ключ не дав доступ до чужої відповіді.
- Термін зберігання ключів - зазвичай 24 години.
- Зберігати відповідь потрібно в тій самій транзакції, що й результат операції, інакше падіння між ними знову дасть подвійне виконання.
- Помилки валідації (4xx) зазвичай зберігають, а тимчасові збої (5xx) - ні, щоб повтор мав шанс пройти.
Саме так працюють Stripe і більшість платіжних API. IETF стандартизує заголовок Idempotency-Key в окремій специфікації.
Опублікований API - контракт з клієнтами, яких ви не контролюєте: мобільні застосунки старих версій, інтеграції партнерів. Їх не можна оновити одночасно з сервером.
Сумісні зміни (можна будь-коли):
- додати новий ендпоінт;
- додати необов'язкове поле в запит;
- додати поле у відповідь (клієнти мають ігнорувати невідомі поля - це варто прописати в документації);
- додати нове значення в перелік - обережно: клієнт зі строгою перевіркою enum може зламатися.
Несумісні (ламаючі): видалити чи перейменувати поле, змінити тип чи формат, зробити поле обов'язковим, змінити зміст коду відповіді, змінити поведінку за замовчуванням.
Версіонування для ламаючих змін:
- в URL -
/v1/orders,/v2/orders: найпростіше й найпомітніше; - в заголовку -
Accept: application/vnd.example.v2+jsonабо власний заголовок; - датою - як Stripe (
Stripe-Version: 2025-03-31): кожен клієнт закріплений на версії API на момент інтеграції, а сервер перетворює відповіді для старих версій.
Плавне виведення старого:
- Оголосити застарілість у документації й журналі змін.
- Додати заголовки:
Deprecation(RFC 9745) - що ресурс застарів,Sunset(RFC 8594) - дата, після якої він перестане працювати, іLinkна документацію з міграцією. - Моніторити використання старої версії за клієнтами й писати тим, хто ще на ній.
- Вимикати лише після дати й коли трафік зійшов нанівець.
Найкращий спосіб уникнути ламаючих змін - продумане проєктування: обгортки-об'єкти замість голих масивів у відповідях (до них можна додати поля), ідентифікатори-рядки, явні формати дат і грошей.
Основні правила:
- Іменники, а не дієслова: дія задається HTTP-методом.
GET /orders,POST /orders,DELETE /orders/42- а не/getOrders,/createOrder. - Множина для колекцій:
/ordersі/orders/42- узгоджено для всього API. - Вкладеність для відношень, але неглибока:
/users/42/orders- так;/users/42/orders/7/items/3/reviews- ні. Ресурс з власним ID краще адресувати напряму:/order-items/3. - Нижній регістр і дефіси:
/payment-methods, а не/paymentMethodsчи/payment_methods. - Фільтрація, сортування, пагінація - у query-параметрах:
/orders?status=paid&sort=-created_at&page[size]=20. - Стабільні ідентифікатори в URL: ID чи UUID, а не назви, які можуть змінитися.
Дії, що не вкладаються в CRUD:
- як під-ресурс стану:
POST /orders/42/cancellation; - як дія-під-ресурс:
POST /orders/42/cancel- прагматично й зрозуміло, і так роблять великі API (Stripe, GitHub); - головне - узгодженість у межах API.
Відповіді:
- Узгоджене іменування полів (
snake_caseчиcamelCase- одне на весь API). - Дати - в ISO 8601 з часовим поясом.
- Гроші - цілими числами в мінімальних одиницях або рядками, з валютою.
- Посилання на пов'язані ресурси чи їхні ID, а не дублювання цілих об'єктів без потреби.
Найважливіше - передбачуваність: розробник, побачивши два ендпоінти, має вгадати третій. Опис в OpenAPI допомагає тримати цю узгодженість і генерувати клієнти.
Безпечний метод не змінює стан на сервері - лише читає. Ідемпотентний метод - повторний виклик з тими самими даними дає той самий стан сервера, що й одиночний.
| Метод | Безпечний | Ідемпотентний |
|---|---|---|
GET, HEAD, OPTIONS |
так | так |
PUT |
ні | так |
DELETE |
ні | так |
POST |
ні | ні |
PATCH |
ні | не гарантовано |
Приклади:
PUT /users/7 {"name": "Оля"}- один раз чи п'ять, результат той самий: ім'я «Оля»;DELETE /orders/42- перший виклик видаляє, наступні нічого не змінюють (відповідь може бути404, але стан однаковий);POST /orders- кожен виклик створює нове замовлення;PATCH {"balance": {"increment": 100}}- не ідемпотентний, аPATCH {"status": "paid"}- фактично ідемпотентний. Тому проPATCHкажуть «не гарантовано».
Ідемпотентність стосується стану, а не відповіді. Відповіді можуть відрізнятися (200 і потім 404 для DELETE), і updated_at може змінитися - важливо, що ефект для клієнта той самий.
Чому це важливо:
- повтори при збоях мережі. Клієнт не отримав відповіді - він не знає, чи запит виконався. Ідемпотентний запит можна безпечно повторити. Неідемпотентний - ні: повтор
POST /paymentsможе списати гроші двічі. Для таких операцій потрібен ключ ідемпотентності; - проксі, браузери, бібліотеки автоматично повторюють і попередньо завантажують безпечні запити. Якщо
GET /logoutчиGET /orders/42/deleteзмінює стан, прийде «невидимий» користувач - пошуковий робот, попереднє завантаження посилань - і виконає дію; - кешування: відповіді на безпечні методи можна кешувати.
Типові помилки:
- зміна стану в
GET(лічильники, «відмітити прочитаним», видалення за посиланням); PUT, реалізований як «додати до наявного» (тоді він не ідемпотентний);POSTдля читання з великим тілом запиту - допустимо як виняток (складний пошук), але відповідь не кешується, і повтор не очевидно безпечний.
У Laravel CSRF-захист і так не перевіряє GET/HEAD/OPTIONS - ще одна причина не змінювати стан у них.
Прочитати - ще не значить знати
20 питань, по одному на екран, ~20 хв. Після завершення - розбір кожної помилки з посиланням на питання.