How to Set Up API Versioning for 1C-Bitrix?

After one update of the trade catalog, we got a dozen calls: partner services stopped processing orders. The reason — the price field in the API response was renamed to base_price. Clients that parsed price received null instead of data. API versioning prevents such incidents: you release a new version — the old one continues to work unchanged. Clients don't have to urgently rewrite integrations, and you avoid reputational losses. For more approaches, see API versioning on Wikipedia.

Without versioning, any change in the response structure becomes a risk. Clients are tightly bound to the data schema, and if you break it, they lose trust in your API. Versioning gives partners predictability: they see that v1 is still alive, receive a deprecation warning, and can calmly plan migration to v2. In our practice, a well-structured version lifecycle reduces support load by 30–40% — fewer urgent requests, less manual coordination with clients. This can save businesses over $5,000 annually in support costs.

Which Versioning Strategy Is Best?

In practice, we use three approaches. Their comparison is in the table:

URL versioning — our recommendation. The version is visible in the URL, easy to test and document. This approach speeds up new partner integrations by 3x compared to query parameters, and is 2x faster to debug than header versioning.

How to Implement API Versioning in 1C-Bitrix?

Step-by-step instructions:

1. Create a folder structure /local/api/v1/, /local/api/v2/.
2. Place controllers and routes.php in each directory.
3. Write a router index.php that extracts the version from the URL.
4. Connect the status configuration (deprecated, current).

Example file structure:

/local/ api/ v1/ controllers/ ProductController.php OrderController.php routes.php v2/ controllers/ ProductController.php # modified version routes.php index.php # version router config.php # status configuration 

The router processes the incoming request, determines the version from the URL, and includes the appropriate route:

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

Version status configuration is stored separately:

return [ 'v1' => ['status' => 'deprecated', 'sunset' => '12 months after deprecated'], 'v2' => ['status' => 'current'], ]; 

The router automatically adds Deprecation, Sunset, and Link headers for deprecated versions.

How Does Inheritance Between API Versions Work?

Version v2 is not written from scratch. We use controller inheritance:

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

This pattern minimizes duplication and eases maintenance. Our experience shows this approach reduces development time for the next version by 40%.

API Version Lifecycle

We implement a standard model: current → deprecated → sunset → retired. When accessing a deprecated version, we add headers:

header('Deprecation: true'); header('Sunset: 12 months'); header('Link: </api/v2/products>; rel="successor-version"'); 

What's Included in the Work

• Audit of current API and its clients
• Designing the versioning scheme
• Developing the router, controllers, and configuration
• Migrating one version (if already exists)
• Documentation (OpenAPI/Swagger)
• Training your team
• Code guarantee (6 months)

Why Monitor Version Usage?

After implementing versioning, it's important to track who and how actively uses each version. Without this data, it's hard to decide when to retire a deprecated version. Basic monitoring is built at the router level: each request is logged with the version, IP address, and endpoint.

// In the router after determining the version $logEntry = [ 'version' => $version, 'endpoint' => $endpoint, 'method' => $_SERVER['REQUEST_METHOD'], 'client_ip' => $_SERVER['REMOTE_ADDR'], 'timestamp' => date('Y-m-d H:i:s'), ]; // Write to a log file or send to a monitoring system error_log(json_encode($logEntry), 3, '/var/log/bitrix-api-usage.log'); 

Analyzing the logs, you see: how many requests per day hit v1, which clients haven't migrated to the new version. This allows you to notify partners specifically and set realistic sunset dates without risking breaking active users. Additionally, aggregating daily metrics: the last request dates from each IP show who already migrated and who still uses the old version. Based on this data, you form a list of clients for personal notification. Practice shows that this approach allows painless deactivation of a deprecated version within 3–6 months after the new version's release, whereas without monitoring, old versions live for years.

The timeline for setting up versioning for an existing API with two versions is 1 to 3 days depending on complexity. We'll assess your project for free — contact us. Get an engineer consultation.

Metrics: over 10 years of experience with Bitrix, 50+ completed API integration projects, 5 years on the market. We guarantee compatibility with 1C-Bitrix and Bitrix24. Savings on integration support — up to 40%.