Налаштування версіонування API 1С-Бітрікс

Налаштування версіонування API 1С-Бітрикс

Версіонування API — це механізм, що дозволяє вносити зміни в API без порушення існуючих інтеграцій. Клієнт, що використовує версію v1, продовжує працювати навіть після випуску v2 зі змінженою структурою відповідей.

Навіщо потрібне версіонування

Без версіонування будь-яка зміна структури відповіді API ломить клієнтів: перейменували поле price в base_price — усі інтеграції перестали працювати. З версіонуванням: у v1 залишається price, у v2 з'являється base_price. Клієнти переходять на v2 у своєму темпі.

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

URL-версіонування — найпоширеніший і зрозумілий підхід:

/api/v1/products
/api/v2/products

Реалізація в Бітриксі через роутинг в /local/php_interface/init.php або через окремий фронт-контролер.

Через заголовок:

GET /api/products
Accept: application/vnd.myapi.v2+json

Менш помітно, але складніше в налагодженні — версія не видна в URL.

Через query-параметр:

GET /api/products?version=2

Простіше реалізувати, але вважається менш «правильним».

Для API на Бітриксі рекомендується URL-версіонування — прозоро, легко тестується, зрозуміло клієнтам.

Структура файлів

/local/
  api/
    v1/
      controllers/
        ProductController.php
        OrderController.php
      routes.php
    v2/
      controllers/
        ProductController.php  ← змінена версія
      routes.php
    index.php  ← маршрутизатор версій

Маршрутизатор версій

// /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;

Успадкування між версіями

Версія v2 не переписується з нуля — успадковує v1 та перевизначає тільки змінене:

// 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);
    }
}

Це мінімізує дублювання коду.

Життєвий цикл версії

При зверненні до deprecated-версії додається заголовок:

header('Deprecation: true');
header('Sunset: Sat, 01 Jan 2026 00:00:00 GMT');
header('Link: </api/v2/products>; rel="successor-version"');

Зберігання інформації про версії

Список версій з їх статусом — в конфігурації:

return [
    'v1' => ['status' => 'deprecated', 'sunset' => '2026-01-01'],
    'v2' => ['status' => 'current'],
];

Маршрутизатор читає конфігурацію та додає потрібні заголовки автоматично.

Налаштування версіонування для існуючого API з двома версіями — 1-2 дні.