Настройка версионирования API 1С-Битрикс: стратегии и реализация

Настройка версионирования API 1С-Битрикс

После одного обновления торгового каталога мы получили десяток обращений: партнёрские сервисы перестали обрабатывать заказы. Причина — поле price в ответе API переименовали в base_price. Клиенты, которые парсили price, ловили null вместо данных. Версионирование API предотвращает такие инциденты: выпускаете новую версию — старая продолжает работать без изменений. Клиентам не приходится срочно переписывать интеграции, а вы избегаете репутационных потерь. Подробнее о подходах — в статье Версионирование API.

Без версионирования любое изменение структуры ответа становится риском. Клиенты жёстко привязаны к схеме данных, и если вы её нарушаете, они теряют доверие к вашему API. Версионирование даёт партнёрам предсказуемость: они видят, что v1 ещё жива, получают предупреждение о deprecation и спокойно планируют миграцию на v2. В нашей практике правильно выстроенный жизненный цикл версий снижает нагрузку на поддержку на 30–40% — меньше срочных обращений, меньше ручной координации с клиентами.

Выбор стратегии версионирования

На практике используем три подхода. Их сравнение — в таблице:

URL-версионирование — наша рекомендация. Версия видна в URL, легко тестируется и документируется. Этот подход в 3 раза ускоряет интеграцию новых партнёров по сравнению с query-параметром.

Реализация версионирования API

Пошаговая инструкция:

1. Создайте структуру папок /local/api/v1/, /local/api/v2/.
2. В каждом каталоге разместите контроллеры и routes.php.
3. Напишите роутер index.php, который извлекает версию из URL.
4. Подключите конфигурацию статусов (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-версий.

Наследование между версиями API

Версия v2 не пишется с нуля. Мы используем наследование контроллеров:

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

Этот паттерн минимизирует дублирование и облегчает поддержку. Наш опыт показывает, что такой подход сокращает время разработки следующей версии на 40%.

Жизненный цикл версии API

Внедряем стандартную модель: current → deprecated → sunset → retired. При обращении к deprecated-версии добавляем заголовки:

header('Deprecation: true'); header('Sunset: через 12 месяцев'); header('Link: </api/v2/products>; rel="successor-version"'); 

Что входит в работу

• Аудит текущего API и его клиентов
• Проектирование схемы версионирования
• Разработка роутера, контроллеров и конфигурации
• Миграция одной версии (если уже есть)
• Документация (OpenAPI/Swagger)
• Обучение вашей команды
• Гарантия на код (6 месяцев)

Мониторинг использования версий

После внедрения версионирования важно отслеживать, кто и насколько активно использует каждую версию. Без этих данных сложно принять решение о сроках отключения 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%.