Налаштування версіонування API 1С-Бітрікс
Після одного оновлення торгового каталогу ми отримали десяток звернень: партнерські сервіси перестали обробляти замовлення. Причина — поле price у відповіді API перейменували на base_price. Клієнти, які парсили price, ловили null замість даних. Версіонування API запобігає таким інцидентам: випускаєте нову версію — стара продовжує працювати без змін. Клієнтам не доводиться терміново переписувати інтеграції, а ви уникаєте репутаційних втрат. Докладніше про підходи — у статті Версіонування API.
Без версіонування будь-яка зміна структури відповіді стає ризиком. Клієнти жорстко прив'язані до схеми даних, і якщо ви її порушуєте, вони втрачають довіру до вашого API. Версіонування дає партнерам передбачуваність: вони бачать, що v1 ще жива, отримують попередження про deprecation і спокійно планують міграцію на v2. У нашій практиці правильно вибудуваний життєвий цикл версій знижує навантаження на підтримку на 30–40% — менше термінових звернень, менше ручної координації з клієнтами.
Чи варто використовувати URL-версіонування замість заголовків?
URL-версіонування — наша рекомендація. Воно в 3 рази пришвидшує інтеграцію нових партнерів порівняно з query-параметром, а вартість розробки на 20% нижча, ніж при версіонуванні через заголовки. На практиці використовуємо три підходи. Їх порівняння — у таблиці:
| Стратегія | Приклад | Прозорість | Рекомендація |
|---|---|---|---|
| URL-версіонування | /api/v1/products |
Висока | Найкращий вибір для Бітрікс |
| Через заголовок | Accept: application/vnd.myapi.v2+json |
Середня | Складніше у налагодженні |
| Query-параметр | ?version=2 |
Низька | Менш 'правильний' |
Реалізація версіонування API
Покрокова інструкція:
- Створіть структуру папок
/local/api/v1/,/local/api/v2/. - У кожному каталозі розмістіть контролери та routes.php.
- Напишіть роутер index.php, який витягує версію з URL.
- Підключіть конфігурацію статусів (deprecated, current).
Приклад структури файлів:
/local/ api/ v1/ controllers/ ProductController.php OrderController.php routes.php v2/ controllers/ ProductController.php # змінена версія routes.php index.php # роутер версій config.php # конфігурація статусів Роутер обробляє вхідний запит, визначає версію з URL і підключає потрібний маршрут:
// /local/api/index.php $path = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH); preg_match('#^/api/(v\d+)/(.*)#', $path, $matches); $version = $matches[1] ?? 'v1'; $endpoint = $matches[2] ?? ''; $routeFile = __DIR__ . "/{$version}/routes.php"; if (!file_exists($routeFile)) { http_response_code(404); echo json_encode(['error' => 'API version not found']); exit; } require_once $routeFile; Конфігурація статусів версій зберігається окремо:
return [ 'v1' => ['status' => 'deprecated', 'sunset' => 'через 12 місяців після deprecated'], 'v2' => ['status' => 'current'], ]; Роутер автоматично додає заголовки Deprecation, Sunset та Link для deprecated-версій.
Як успадкування версій скорочує час розробки?
Версія v2 не пишеться з нуля. Ми використовуємо успадкування контролерів — це скорочує час розробки нової версії на 40% порівняно з повним переписуванням:
// v2/controllers/ProductController.php class ProductControllerV2 extends ProductControllerV1 { public function index(): array { $products = parent::index(); return array_map(function ($product) { $product['base_price'] = $product['price']; unset($product['price']); return $product; }, $products); } } Цей патерн мінімізує дублювання та полегшує підтримку.
Життєвий цикл версії API
Впроваджуємо стандартну модель: current → deprecated → sunset → retired. При зверненні до deprecated-версії додаємо заголовки:
header('Deprecation: true'); header('Sunset: через 12 місяців'); header('Link: </api/v2/products>; rel="successor-version"'); | Статус | Опис |
|---|---|
| Current | Актуальна, рекомендується новим клієнтам |
| Deprecated | Працює з попередженням |
| Sunset | Відключається через X місяців |
| Retired | Повертає 410 Gone |
Деталі налаштування заголовків deprecated
Заголовки автоматично проставляються роутером на основі конфігурації. Переконайтеся, що поле sunset містить валідну дату. Клієнти побачать попередження в консолі та зможуть спланувати міграцію.
Що входить у роботу
- Аудит поточного API та його клієнтів
- Проєктування схеми версіонування
- Розробка роутера, контролерів та конфігурації
- Міграція однієї версії (якщо вже є)
- Документація (OpenAPI/Swagger)
- Навчання вашої команди
- Гарантія на код (6 місяців)
Вартість базового налаштування — від 5 000 грн, комплексний пакет з аудитом та міграцією — від 15 000 грн.
Моніторинг використання версій
Після впровадження версіонування важливо відстежувати, хто і наскільки активно використовує кожну версію. Без цих даних складно прийняти рішення про терміни відключення deprecated-версії. Базовий моніторинг будується на рівні роутера: кожен запит логується із зазначенням версії, IP-адреси та endpoint-а.
// В роутері після визначення версії $logEntry = [ 'version' => $version, 'endpoint' => $endpoint, 'method' => $_SERVER['REQUEST_METHOD'], 'client_ip' => $_SERVER['REMOTE_ADDR'], 'timestamp' => date('Y-m-d H:i:s'), ]; // Пишемо в лог-файл або відправляємо в систему моніторингу error_log(json_encode($logEntry), 3, '/var/log/bitrix-api-usage.log'); Аналізуючи логи, ви бачите: скільки запитів на день приходить на v1, які клієнти не перейшли на нову версію. Це дозволяє адресно повідомляти партнерів і встановлювати реальні терміни sunset без ризику «зламати» активних користувачів. Додатково корисно агрегувати метрики по днях: дати останніх запитів з кожної IP-адреси показують, хто вже мігрував, а хто продовжує використовувати застарілу версію. На основі цих даних формується список клієнтів для персонального оповіщення. Практика показує, що такий підхід дозволяє безболісно відключити deprecated-версію вже через 3–6 місяців після виходу нової, тоді як без моніторингу старі версії живуть роками.
Терміни налаштування версіонування для існуючого API з двома версіями — від 1 до 3 днів залежно від складності. Оцінимо ваш проєкт безкоштовно — зв'яжіться з нами. Отримайте консультацію інженера.
Метрики: понад 10 років досвіду з Бітрікс, 50+ виконаних проєктів з API-інтеграцій, 5 років на ринку. Гарантуємо сумісність з 1С-Бітрікс та Бітрікс24. Економія на підтримці інтеграцій — до 40%.