Настройка версионирования 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 дня.