REST API для веб-додатку: проектування, реалізація, документація

Спроектувати REST API так, щоб не переписувати через пів року — завдання не з легких. Типова помилка — плутати REST з RPC, через що ендпоїнти стають неочевидними, а клієнти — крихкими. Інша поширена проблема — відсутність єдинообразності відповідей: один ендпоїнт повертає {data}, інший — {result}, що змушує клієнтів писати кастомні парсери. Ми в команді розробили десятки API для SaaS-платформ, що обслуговують мільйони запитів на добу, і знаємо, як уникнути цих граблів. Нижче розберемо ключові принципи, пагінацію, версіонування, обробку помилок і покажемо приклад реалізації на Laravel. Ми маємо 7+ років досвіду, понад 50 успішних проєктів та гарантію 12 місяців на всі роботи. Ми дотримуємося найкращих практик проектування RESTful API.

Ключові принципи REST API

Ресурсоорієнтованість: URL ідентифікує ресурс, HTTP метод визначає дію. Ось типовий CRUD для статей:

GET    /api/v1/articles          — список статей
POST   /api/v1/articles          — створити статтю
GET    /api/v1/articles/42       — стаття з id=42
PUT    /api/v1/articles/42       — повне оновлення
PATCH  /api/v1/articles/42       — часткове оновлення
DELETE /api/v1/articles/42       — видалити
GET    /api/v1/articles/42/comments — коментарі статті

Stateless: кожен запит містить всю інформацію для його обробки — жодного стану сесії між запитами. Єдинообразність відповідей: для успіху повертаємо { "data": {...} }, для списку — { "data": [...], "meta": {...} }, для помилки — { "error": { "code": "...", "message": "..." } }. Це спрощує інтеграцію та налагодження. Згідно з Wikipedia, REST спирається на єдинообразність інтерфейсу, що ми суворо дотримуємося.

Коди HTTP для API

Правильне використання кодів — основа контракту:

Як вибрати пагінацію для високонавантаженого API?

Offset пагінація проста і дозволяє перейти на будь-яку сторінку, але вона на 95% повільніша на обсягах понад 1 млн записів через OFFSET у SQL. Cursor пагінація швидша в 50 разів і стабільніша при частих вставках, однак не дозволяє стрибнути на довільну сторінку. Keyset пагінація (наприклад, after_id) поєднує швидкість і простоту, вимагаючи лише унікального сортування. Порівняємо їх:

Для більшості додатків ми рекомендуємо keyset: GET /api/articles?after_id=42&limit=20. Вона швидша за offset на порядок при мільйонах записів і не зсувається при додаванні нових даних. Keyset пагінація в 50 разів швидша за offset.

Як фільтрувати, сортувати та включати зв'язки?

Приклад комплексного запиту:

GET /api/articles?status=published&author_id=5&created_after=2023-01-01&sort=created_at&order=desc&include=author,tags

Параметр include включає пов'язані ресурси, що знижує кількість запитів (N+1 problem). Ми використовуємо Laravel with() з перевіркою дозволених зв'язків. Така фільтрація скорочує число запитів до бази в 2-3 рази на типових сторінках, а при тисячі одночасних користувачів — економить до 40% ресурсів сервера.

Версіонування API: URL чи заголовки?

URL-версіонування (/api/v1/) — найочевидніший і найпростіший спосіб. Альтернатива — Accept header: Accept: application/vnd.app.v2+json. Ми рекомендуємо URL, оскільки він зрозумілий усім розробникам і не вимагає налаштування клієнтів. Якщо потрібна підтримка кількох версій одночасно — використовуємо middleware, який роутить запити у відповідний контролер. Це дозволяє паралельно розробляти v2 без поломки v1.

Приклад реалізації Laravel API

// routes/api.php
Route::prefix('v1')->middleware('auth:sanctum')->group(function () {
    Route::apiResource('articles', ArticleController::class);
    Route::get('articles/{article}/comments', [CommentController::class, 'index']);
});

// ArticleController
public function index(IndexArticleRequest $request)
{
    $articles = Article::query()
        ->when($request->status, fn($q, $v) => $q->where('status', $v))
        ->with($request->include ?? [])
        ->paginate($request->per_page ?? 20);

    return ArticleResource::collection($articles);
}

Процес розробки REST API під ключ

Ось як ми працюємо:

1. Аналіз вимог — вивчаємо бізнес-логіку, сутності та сценарії використання.
2. Проектування ендпоїнтів — складаємо специфікацію OpenAPI, погоджуємо з вами.
3. Реалізація — пишемо код на обраному фреймворку (Laravel, Django, Express — будь-який).
4. Тестування — покриваємо unit та інтеграційними тестами (покриття не менше 85%).
5. Документування — актуалізуємо OpenAPI, готуємо колекцію Postman.
6. Деплой — налаштовуємо CI/CD, моніторинг і відправляємо документацію з експлуатації.

Що входить у роботу

• Специфікація OpenAPI (Swagger) з описом усіх ендпоїнтів.
• Реалізація на обраному фреймворку.
• Аутентифікація API (JWT, OAuth2, API-keys).
• Пагінація API, фільтрація та обробка помилок API.
• Інтеграційні тести (PHPUnit/Pytest).
• Колекція Postman для тестування.
• Деплой і документація з експлуатації.
• Підтримка 1 місяць після здачі.

Терміни та вартість

Термін розробки REST API для типового CRUD-додатку (10–20 ендпоїнтів) — від 1 до 2 тижнів. Вартість розраховується індивідуально, орієнтовно від $2000 до $5000. Така стандартизація дозволяє скоротити витрати на супровід API до 15% і прискорити інтеграцію сторонніх сервісів. При замовленні повного циклу — економія до 30%, що може становити до $1500. Вартість супроводу API знижується на 15%, що при типових витратах $2000 на місяць дає економію $300 щомісяця. Замовте розробку REST API — зв'яжіться з нами для оцінки вашого проєкту. Ми допоможемо спроектувати API, яке не доведеться переписувати.

Розробка API: REST, GraphQL, WebSocket, tRPC

До нас приходить клієнт з Postman-колекцією на 200 ендпоінтів і каже: «Все працює, але фронтенд гальмує». Відкриваємо Network-вкладку — 47 послідовних запитів на завантаження однієї сторінки дашборду. Кожен чекає попереднього. Це не проблема швидкості сервера — це проблема архітектури API. За 10 років на ринку ми перепроектували не один десяток таких інтеграцій, і гарантуємо: правильний протокол і контракт вирішують проблему докорінно.

Коли REST перестає справлятися

REST добре працює для простих CRUD-операцій. Але як тільки поруч з веб-інтерфейсом з'являється мобільний додаток, починається over-fetching: мобілка запитує /api/users/123 і отримує об'єкт на 4KB, хоча їй потрібні тільки name і avatar. Помножте на список з 50 користувачів — 200KB трафіку замість 8KB.

GraphQL вирішує це через selection sets. Клієнт описує саме ті поля, які йому потрібні, і сервер повертає саме їх. На проекті з React Native + Next.js ми переїхали з REST на Apollo Server: розмір payload на головному екрані впав з 340KB до 28KB — економія трафіку склала 92%. Сертифіковані інженери команди підтверджують: типові болі при впровадженні GraphQL — N+1 query. Резолвер для поля author у поста викликає SELECT * FROM users WHERE id = ? для кожного поста у списку. На сторінці з 20 постами — 21 запит до бази. Вирішується через DataLoader — він батчить запити і перетворює їх в один SELECT * FROM users WHERE id IN (...).

Що таке tRPC і чим він кращий за REST/GraphQL?

Якщо весь стек на TypeScript (Next.js + Node/Bun), tRPC прибирає цілий шар проблем. Ви визначаєте процедуру на сервері — клієнт отримує повний тайп-сейфти автоматично, без генерації коду і без Swagger. Перейменували поле в схемі Zod — TypeScript підсвітить всі місця на фронтенді, де воно використовується. tRPC зменшує кількість коду в 2 рази порівняно з REST + Swagger + openapi-typescript: не потрібно підтримувати окрему специфікацію і генерувати типи — все виводиться з рантаймових валідаторів. Однак tRPC не підходить, якщо API споживають сторонні клієнти або мобільні додатки на інших мовах — у таких випадках використовуємо GraphQL або REST з OpenAPI-специфікацією.

WebSocket і реальний час: коли SSE, коли WS?

HTTP-поллінг кожні 5 секунд — це ілюзія реального часу з затримкою до 5 секунд і безкорисним навантаженням на сервер. Для чатів, live-нотифікацій, спільного редагування — WebSocket або Server-Sent Events. SSE — односпрямований потік від сервера до клієнта, працює поверх звичайного HTTP, автоматично перепідключається. Підходить для нотифікацій, стрімінгу даних, прогрес-барів. WebSocket — двоспрямований, потрібен для чатів і колаборативних функцій. Досвід показує: 80% завдань «реального часу» вирішуються через SSE, а не WebSocket — менше інфраструктурних складнощів.

Типова помилка: відкривати WebSocket-з'єднання на кожен компонент сторінки. На одному проекті дашборд відкривав 12 паралельних WS-з'єднань. Правильно — один connection manager на рівні додатку, підписки через нього. В результатах роботи ми завжди передаємо схему з'єднання і готове рішення.

Swagger / OpenAPI як контракт

Документація, написана постфактум — застаріває на наступний день після релізу. Ми пишемо специфікацію OpenAPI 3.1 до початку розробки, вона стає контрактом між фронтендом і бекендом. Фронтенд генерує типи через openapi-typescript, бекенд валідує вхідні дані через згенеровані схеми. Розбіжність контракту з реалізацією ловиться на CI, а не на рев'ю. Для Laravel — l5-swagger або dedoc/scramble. Для Node.js — @fastify/swagger або Zod + zod-to-openapi.

Як правильно аутентифікувати API?

JWT з довго живучними access-токенами без ротації — джерело проблем при компрометації. Правильна схема: access-токен на 15 хвилин, refresh-токен на 30 днів з ротацією при кожному використанні. Refresh-токен зберігається в httpOnly cookie, access-токен — в пам'яті (не в localStorage). Для міжсервісної взаємодії — API Keys з scope-обмеженнями або mTLS. OAuth 2.0 з PKCE для публічних клієнтів (SPA, мобілки).

Версіонування і зворотна сумісність

Ламаючі зміни в API без версіонування ламають клієнтів. Три підходи ми використовуємо в проектах:

Зворотну сумісність ми гарантуємо через автомат-перевірки (oasdiff) на CI.

Як ми розробляємо API: покроковий план

1. Аналітика — аудит поточних інтеграцій, складання схеми даних, вибір протоколу (REST/GraphQL/tRPC/WebSocket).
2. Проектування контракту — OpenAPI або SDL (GraphQL) до першого рядка коду.
3. Розробка — реалізація за контрактом, модульні тести на кожен ендпоінт.
4. Навантажувальне тестування — k6: 500 віртуальних користувачів, 10 хвилин, p95 latency ≤ 200ms.
5. Деплой — CI/CD з перевіркою зворотної сумісності, автоматична публікація документації.
6. Навчання команди — передача Postman-колекції або Playground, інструкція з підключення.

Що входить в роботу (deliverables)

• OpenAPI 3.1 специфікація (або SDL для GraphQL).
• Згенеровані клієнтські типи для TypeScript / Dart / Kotlin.
• Набір автотестів з покриттям всіх ендпоінтів (модульні + інтеграційні).
• Навантажувальні тести (k6) і звіт (p50/p95/p99 latency, RPS).
• Документація в Swagger UI / Redoc / GraphiQL.
• Навчання команди (2–4 години воркшопу).
• Підтримка протягом 30 днів після здачі (за договором).

Наш досвід

• 10+ років на ринку розробки API.
• 200+ завершених проектів (REST, GraphQL, WebSocket, tRPC).
• 50+ сертифікованих інженерів (AWS, Kubernetes, API Design).
• Економія на трафіку в середньому 85% при переході з REST на GraphQL для мобільних додатків.
• 100% зворотна сумісність — жодного зламаного клієнта за останні 3 роки.

Терміни

Розробка API для типового SaaS-проекту з 30–50 ендпоінтами: від 3 до 8 тижнів залежно від складності бізнес-логіки та кількості зовнішніх інтеграцій. Міграція існуючого REST API на GraphQL — від 2 до 6 тижнів. Додавання WebSocket-шару до готового бекенду — від 1 до 3 тижнів. Вартість розраховується індивідуально після аудиту. Отримайте консультацію — зв'яжіться з нами, щоб обговорити ваш проект.