REST API: Загальний
20 питань · ~18 хв · Версія v3.0
Увійдіть, щоб продовжити
HTTP-методи й статус-коди, дизайн ресурсів, пагінація, кешування, ідемпотентність, автентифікація, помилки й API у Laravel.
- За спробу
- 20
- У пулі
- 100
- Проходжень
- 7
- Середній бал
- 57%
- Пройшли на 70%+
- 0%
Питання для підготовки
100 питань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на документацію з міграцією. - Моніторити використання старої версії за клієнтами й писати тим, хто ще на ній.
- Вимикати лише після дати й коли трафік зійшов нанівець.
Найкращий спосіб уникнути ламаючих змін - продумане проєктування: обгортки-об'єкти замість голих масивів у відповідях (до них можна додати поля), ідентифікатори-рядки, явні формати дат і грошей.
SSRF (Server-Side Request Forgery) - зловмисник змушує ваш сервер зробити запит туди, куди йому потрібно. Типові функції-мішені: імпорт за URL, попередній перегляд посилань, вебхуки (користувач вказує URL для сповіщень), завантаження аватара за посиланням, генерація PDF з HTML.
// вразливо
$image = Http::get($request->input('avatar_url'))->body();
Що можна дістати через ваш сервер:
- сервіси метаданих хмари:
http://169.254.169.254/- тимчасові облікові дані AWS/GCP/Azure. Класичний сценарій масштабних витоків; - внутрішні сервіси, недоступні ззовні: адмінки, бази з HTTP-інтерфейсом, Redis, панелі моніторингу,
localhost:8080; - сканування внутрішньої мережі за часом відповіді;
- файли через схеми
file://,gopher://- залежно від HTTP-клієнта.
Захист (кілька шарів, бо кожен окремо обходиться):
1. Дозволений список, а не заборонений. Якщо можна - лише відомі домени (інтеграції з конкретними сервісами).
2. Схема й порт: лише https (за потреби http), стандартні порти.
3. Перевірка IP після розв'язання DNS: заборонити приватні діапазони (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), 127.0.0.0/8, link-local 169.254.0.0/16, IPv6-аналоги (::1, fc00::/7, fe80::/10).
Пастки, через які наївна перевірка не працює:
- DNS rebinding: домен при перевірці дає публічну адресу, а при реальному запиті - внутрішню. Перевіряти треба той IP, до якого реально підключаєтесь (зафіксувати розв'язану адресу для з'єднання);
- редиректи: перевірений URL повертає
302наhttp://169.254.169.254/. Редиректи вимкнути або перевіряти кожен крок; - альтернативні записи IP:
http://2130706433/,http://0x7f.1/,http://[::ffff:127.0.0.1]/- усе це127.0.0.1.
4. Мережева ізоляція: вихідні запити до користувацьких URL - через окремий проксі чи сервіс без доступу до внутрішньої мережі й метаданих. Найнадійніший шар.
5. Хмара: IMDSv2 на AWS (сесійний токен для метаданих) робить класичну атаку значно складнішою.
6. Обмеження відповіді: тайм-аути, максимальний розмір, перевірка типу вмісту - і не повертати клієнту сирі відповіді чи детальні помилки підключення (це дає зловмиснику «сліпе» сканування).
Для вебхуків з URL від користувача - ті самі правила плюс перевірка URL при збереженні й при кожній відправці.
Навіщо два різні токени:
- токен доступу - короткоживучий (хвилини), надсилається з кожним запитом. Якщо його вкрадуть - шкода обмежена часом;
- refresh-токен - довгоживучий (дні, тижні), використовується лише для отримання нового токена доступу і лише на ендпойнті авторизації.
Це компроміс між безпекою (короткі токени доступу) і зручністю (користувач не вводить пароль щогодини).
Чому refresh-токен - найцінніша мішень: хто його має, той може безстроково отримувати нові токени доступу. Тому RFC 9700 (найкращі практики безпеки OAuth 2.0) вимагає для публічних клієнтів (SPA, мобільні застосунки) або прив'язки токена до клієнта (DPoP, mTLS), або ротації.
Ротація refresh-токенів: кожне оновлення видає новий refresh-токен, а старий стає недійсним.
refresh_1 → (access_2, refresh_2) refresh_1 недійсний
refresh_2 → (access_3, refresh_3) refresh_2 недійсний
Виявлення повторного використання - головна перевага ротації:
- зловмисник викрав
refresh_2і скористався ним першим - отримавrefresh_3; - легітимний клієнт пізніше пред'являє
refresh_2- вже використаний; - сервер розуміє, що один з двох - зловмисник, і відкликає всю сім'ю токенів (усі, що походять від початкового входу). Обидва мусять увійти заново, а зловмисник втрачає доступ.
Для цього сервер зберігає ланцюжок: кожен refresh-токен знає свою «сім'ю» і чи був використаний.
Практичні деталі:
- паралельні запити: дві вкладки одночасно оновлюють токен з тим самим refresh-токеном - друга виглядає як «повторне використання». Рішення - короткий період допуску для того самого токена або серіалізація оновлення на клієнті;
- абсолютний термін життя сесії: навіть з ротацією ланцюжок не повинен жити вічно (наприклад, 30-90 днів до повторного входу);
- відкликання при зміні пароля і виході - усіх refresh-токенів користувача;
- зберігання: хеш у базі (як паролі); на клієнті - захищене сховище ОС для мобільних,
HttpOnly-cookie для вебу.
Для браузерних SPA взагалі варто зважити, чи потрібні токени: сесійна cookie з бекендом на тому ж домені (Sanctum SPA) чи патерн BFF (бекенд для фронтенду, що тримає токени на сервері) прибирають токени з браузера.
У Laravel Passport refresh-токени є з коробки; терміни задаються Passport::tokensExpireIn() і Passport::refreshTokensExpireIn().
Докладніше в документації: RFC 9700: найкращі практики безпеки OAuth 2.0
Прочитати - ще не значить знати
20 питань, по одному на екран, ~18 хв. Після завершення - розбір кожної помилки з посиланням на питання.