Пошук уроків, статей та іншого контенту
Що насправді робить API «RESTful» — не просто «API поверх HTTP», а конкретний набір принципів проєктування ресурсів.
REST (Representational State Transfer) — архітектурний стиль, а не протокол чи стандарт із формальною специфікацією. «RESTful API» означає не просто «API, доступне по HTTP» (стаття «REST vs GraphQL» цієї платформи порівнює REST із альтернативним підходом), а дотримання конкретного набору принципів проєктування навколо поняття ресурсу.
У REST URL описує ресурс (іменник), а дію над ним визначає HTTP-метод — а не сам URL:
Погано (дія в URL): GET /getUserOrders?id=42
Добре (ресурс в URL): GET /users/42/orders
Погано: POST /createOrder
Добре: POST /orders
Погано: POST /deleteOrder?id=7
Добре: DELETE /orders/7GET /orders — отримати список замовлень.
GET /orders/7 — отримати конкретне замовлення.
POST /orders — створити нове замовлення.
PUT /orders/7 — повністю замінити замовлення 7.
PATCH /orders/7 — частково оновити замовлення 7.
DELETE /orders/7 — видалити замовлення 7.
Використання стандартного словника HTTP-методів означає, що будь-хто, знайомий з REST, одразу розуміє, що робить ендпоінт, лише побачивши метод і шлях — без читання документації для кожної окремої дії.
REST API використовує коди статусу HTTP-відповіді змістовно, а не завжди повертає 200 з полем success у тілі: 200 OK для успіху, 201 Created для успішного створення ресурсу, 204 No Content для успішного видалення (без тіла відповіді), 400 Bad Request для помилки валідації, 401 Unauthorized/403 Forbidden для проблем автентифікації/авторизації, 404 Not Found для відсутнього ресурсу.
Вкладені шляхи (/users/42/orders) добре передають ієрархічний зв'язок «замовлення належать конкретному користувачу», але глибока вкладеність (/users/42/orders/7/items/3/reviews) швидко стає незручною. Практичний орієнтир: вкладати не більше одного рівня, а для доступу до глибоко вкладеного ресурсу окремо використовувати його власний ідентифікатор (/reviews/99 замість довгого ланцюжка).
Оскільки контракт API з часом змінюється, а клієнти (мобільні застосунки, сторонні інтеграції) не завжди можуть оновитись миттєво, REST API зазвичай версіонують — найпоширеніше через префікс шляху (/api/v1/orders) або заголовок запиту — щоб мати можливість вносити зворотно несумісні зміни в новій версії, не ламаючи наявних клієнтів старої.
Використовувати дієслова в URL замість HTTP-методів (/getUsers, /createOrder) — робить API непослідовним і змушує вивчати кожен ендпоінт окремо, замість покладатись на спільний словник методів.
Завжди повертати 200 OK з полем { success: false } у тілі при помилці — ламає стандартну обробку помилок на боці клієнта (fetch/axios очікують перевіряти саме статус-код) і ускладнює моніторинг/логування на рівні інфраструктури, яка зазвичай орієнтується на HTTP-статуси.
Ламати контракт API без версіонування — зміна формату відповіді чи видалення поля в наявному ендпоінті без нової версії ламає всіх клієнтів, які не встигли оновитись синхронно з бекендом.
REST організовує API навколо ресурсів (іменники в URL) і використовує HTTP-методи як стандартний словник дій над ними, а коди статусу — як змістовну частину відповіді, а не формальність. Ці принципи роблять API передбачуваним для будь-кого, хто вже знайомий з REST, без потреби вивчати документацію кожного окремого ендпоінта з нуля.