Версіонування API для веб-застосунку: стратегії та реалізація

Версіонування API для веб-застосунку

Уявіть: ви додали у відповідь API нове поле, і мобільний застосунок партнера перестав працювати. Така ситуація коштувала одному з наших клієнтів 3 дні екстреного викочування патча. Впровадження версіонування API для веб-застосунку вирішило проблему раз і назавжди. Без версіонування API будь-яка зміна ламає інтеграції. Ми впровадили версіонування для 30+ проєктів — від стартапів до enterprise. Досвід показує: правильна стратегія зберігає сумісність і економить до 40% часу на підтримку, що в грошовому еквіваленті становить значну суму на рік на проєкт.

Типовий кейс: клієнтська база зросла, знадобилося додати у відповідь список тегів з ID замість рядків. Оновлення мобільного застосунку планувалося через два місяці — весь цей час старі версії мають працювати. Версіонування дозволило зробити це без даунтайму та без правок з боку клієнтів.

Чому версіонування API критичне для веб-застосунків?

У production API обслуговує десятки клієнтів з різними версіями коду. Ви не можете змусити їх оновитися миттєво. Версіонування дає можливість випускати нові можливості, зберігаючи працездатність старих клієнтів. Без нього команда або заморожує API, або додає костилі на кшталт флагів і полів-дублерів, що ускладнює код і веде до помилок.

Основні стратегії версіонування

На практиці URL-версіонування в 2 рази простіше для кешування, ніж header-версіонування. Header-версіонування складніше тестувати через приховані заголовки. Query-параметри не рекомендуються, оскільки змішують версію з бізнес-логікою. Для публічних API з великою кількістю клієнтів вибирайте URL-версіонування. Якщо API вже в production і змінити URL неможливо — використовуйте header. Як зазначено в документації OpenAPI, URL-версіонування — бажаний підхід.

Як реалізувати версіонування в популярних фреймворках?

Laravel (PHP 8.3+)

// routes/api.php
Route::prefix('v1')->group(base_path('routes/api_v1.php'));
Route::prefix('v2')->group(base_path('routes/api_v2.php'));

// routes/api_v2.php
Route::apiResource('articles', App\Http\Controllers\V2\ArticleController::class);

Контролери V2 успадковують від V1, перевизначаючи лише методи, що змінилися:

namespace App\Http\Controllers\V2;
use App\Http\Controllers\V1\ArticleController as V1Controller;
class ArticleController extends V1Controller
{
    public function index(Request $request)
    {
        // V2: додали поле excerpt, прибрали body зі списку
        return ArticleV2Resource::collection(
            Article::paginate($request->per_page ?? 20)
        );
    }
}

NestJS (Node.js)

// main.ts
app.setGlobalPrefix('api');
app.enableVersioning({ type: VersioningType.URI });

@Controller({ path: 'articles', version: '2' })
export class ArticleV2Controller {
  @Get()
  findAll() { ... }
}

Як управляти життєвим циклом версій?

Типовий процес:

1. Нова версія анонсується в CHANGELOG зі списком breaking changes.
2. Стара версія позначається як deprecated — у відповіді додають заголовки Deprecation і Sunset.
3. Через 6–12 місяців після анонсу стара версія вимикається.

// Middleware додає Deprecation-заголовок до V1-відповідей
class AddDeprecationHeader
{
    public function handle($request, Closure $next)
    {
        $response = $next($request);
        if (str_starts_with($request->path(), 'api/v1/')) {
            $sunsetDate = now()->addMonths(6)->toRfc7231String();
            $response->headers->set('Deprecation', 'true');
            $response->headers->set('Sunset', $sunsetDate);
            $response->headers->set('Link', '<https://api.example.com/v2/>; rel="successor-version"');
        }
        return $response;
    }
}

Що є breaking change?

Не всі зміни потребують нової версії. Нижче таблиця для швидкої перевірки:

Backward-compatible зміни: додавання поля, додавання опціонального параметра запиту, додавання ендпоінту. Breaking changes, що потребують нової версії: видалення поля, перейменування, зміна типу, видалення ендпоінту.

Які метрики покращує версіонування?

Правильне версіонування знижує кількість інцидентів, пов'язаних зі змінами API, на 60–70%. Час на інтеграцію нових клієнтів скорочується в 2–3 рази, оскільки вони можуть використовувати актуальну версію без очікування оновлення старих. Наші замовники відзначають, що після впровадження версіонування витрати на підтримку API зменшуються на 30% вже в перший квартал. Середня економія бюджету клієнта становить від кількох сотень тисяч до мільйона гривень на рік на підтримці застарілих версій.

Що входить в роботу з впровадження версіонування?

Ми надаємо:

• Аудит поточного API та виявлення залежностей
• Вибір оптимальної стратегії (URL/header)
• Реалізацію роутингу та успадкування контролерів
• Налаштування Deprecation-заголовків та Sunset-дати
• Створення та підтримку CHANGELOG
• OpenAPI-специфікації для кожної версії
• Навчання команди роботі з версіонуванням

Строки та вартість

Налаштування базового URL-версіонування з розведенням роутів і успадкуванням займає від 2 до 3 днів. Повний цикл з автоматичним changelog, Sunset-моніторингом та окремими OpenAPI-файлами — до тижня. Вартість розраховується індивідуально під ваш проєкт. Оцінимо задачу після короткого дзвінка — зв'яжіться з нами.

Гарантуємо сумісність з існуючими клієнтами та документальну підтримку. Замовте впровадження версіонування у вашому проєкті — наші інженери допоможуть вибрати оптимальну стратегію. Отримайте консультацію щодо вашого проєкту.

Розробка 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 тижнів. Вартість розраховується індивідуально після аудиту. Отримайте консультацію — зв'яжіться з нами, щоб обговорити ваш проект.