Увійти Реєстрація
Вакансії
Вакансії Laravel Компанії Статистика
Підготовка
Як підготуватися Співбесіди Тестування Документація
Блог
Всі статті Серії
Екосистема
Пакети Ресурси Проєкти Інструменти Події Відео
Інше
Про нас Реклама

Як організувати версіонування API в Laravel-застосунку?

Версія в URL - найпоширеніший і найпростіший для клієнтів варіант:

// bootstrap/app.php
->withRouting(
    api: __DIR__.'/../routes/api.php',
    apiPrefix: 'api',
    then: function () {
        Route::middleware('api')->prefix('api/v2')->name('v2.')
            ->group(base_path('routes/api_v2.php'));
    },
)
routes/api.php     →  /api/v1/...  (або /api/...)
routes/api_v2.php  →  /api/v2/...

Альтернативи - версія в заголовку (Accept: application/vnd.myapp.v2+json) чи окремий параметр. Вони «чистіші» з погляду REST, але гірше видимі в логах, кешах CDN і при налагодженні.

Що саме відрізняється між версіями - здебільшого формат даних, а не бізнес-логіка. Тому дублювати весь код не потрібно:

app/Http/Controllers/Api/V1/OrderController.php
app/Http/Controllers/Api/V2/OrderController.php   ← тонкі контролери
app/Http/Resources/V1/OrderResource.php
app/Http/Resources/V2/OrderResource.php           ← різний формат відповіді
app/Actions/CreateOrder.php                         ← спільна логіка
  • ресурси й Form Request-и - за версіями (формат входу й виходу);
  • сервіси, actions, моделі, політики - спільні;
  • нова версія створюється лише для ендпойнтів, що змінилися; решта може посилатися на контролери попередньої версії.

Коли нова версія потрібна - лише для ламаючих змін: перейменування чи видалення полів, зміна типів, обов'язкові нові параметри, зміна семантики. Додавання нових полів і ендпойнтів - не привід для нової версії.

Підтримка старих версій:

  • заголовки застарівання на відповідях старої версії (Deprecation, Sunset з датою вимкнення) і посилання на інструкцію з міграції;
  • моніторинг використання: скільки запитів і від яких клієнтів іде на стару версію - без цього неможливо вирішити, коли її вимикати;
  • мобільні клієнти оновлюються роками - стара версія може жити довго, тож кожна нова версія - це додаткова підтримка.

Тестування: набори тестів для кожної підтримуваної версії - зміна спільної логіки не має ламати стару версію.

Альтернатива версіям - еволюція без ламання: додавати, але не змінювати; нові поля замість зміни старих; «розширювані» енуми. Багато команд обходяться однією версією роками, якщо дотримуються цих правил.

Докладніше в документації: Laravel: групи маршрутів

Перевір себе

20 випадкових питань за спробу, після завершення - розбір кожної помилки

Схожі питання