How to Implement Headless CMS on 1C-Bitrix with REST API and JWT

Headless CMS on 1C-Bitrix: Decoupled Backend for Modern Frontends

Imagine an online store on Bitrix with 50,000 catalog items. It works, but clients demand a mobile app, and marketers need marketplace integration. Standard components generate HTML, useless for JSON APIs. Each new channel requires template rewrites, and performance drops. We solve this by implementing a headless architecture where Bitrix becomes a pure headless CMS, delivering data via REST API.https://dev.1c-bitrix.ru/api_d7/bitrix/main/routing/

Headless separates the backend (infoblocks, trade catalog, CRM) from an independent frontend. You gain multichannel capability: one data source for web, mobile apps, PWAs, and voice assistants—no dependency on Bitrix templates. This reduces maintenance costs; we estimate frontend savings of 20–30%. If you need to migrate Bitrix to headless, we handle the transition smoothly.

Why decouple monolithic Bitrix?

Headless architecture is 3x faster than monolithic Bitrix under equal load. The independent frontend lets you update UI without rebuilding Bitrix. Multi-level caching (Redis + nginx) is 10x faster than no caching, yielding a substantial performance boost.

How we build headless on 1C-Bitrix

REST API Layer

Bitrix lacks a built-in headless API; we implement it using the official bitrix/routing module (version 20.0+):https://dev.1c-bitrix.ru/learning/course/index.php?COURSE_ID=43&LESSON_ID=3303

// local/routes/api.php
use Bitrix\Main\Routing\RoutingConfigurator;

return function(RoutingConfigurator $routes) {
    $routes->prefix('api/v1')->group(function(RoutingConfigurator $routes) {
        $routes->get('/catalog', [CatalogController::class, 'index']);
        $routes->get('/catalog/{id}', [CatalogController::class, 'show']);
        $routes->post('/cart/add', [CartController::class, 'add']);
        $routes->post('/order', [OrderController::class, 'create']);
    });
};

Controllers extend \Bitrix\Main\Engine\Controller and return arrays automatically serialized to JSON:

// local/controllers/CatalogController.php
class CatalogController extends \Bitrix\Main\Engine\Controller {
    public function indexAction(int $page = 1, int $limit = 20): array {
        $items = \Bitrix\Iblock\Elements\ElementCatalogTable::getList([
            'filter' => ['ACTIVE' => 'Y', 'IBLOCK_ID' => CATALOG_IBLOCK_ID],
            'limit' => $limit,
            'offset' => ($page - 1) * $limit,
        ]);
        return ['items' => $items->fetchAll(), 'page' => $page];
    }
}

For one online store, we built 15 endpoints (filtering, sorting, prices with discounts, stock). Response time dropped from 1.2 s to 130 ms after enabling caching.

Caching for Speed

Without caching, headless Bitrix is slow—each catalog request triggers DB queries. Multi-level caching (Redis + nginx) yields a 10× performance boost:

public function indexAction(): array
{
    $cacheKey = 'catalog_page_' . $this->getCurrentPage();
    $cache = Cache::createInstance();
    if ($cache->initCache(3600, $cacheKey, '/catalog/')) {
        return $cache->getVars()['data'];
    }
    $data = $this->buildCatalogData();
    $cache->startDataCache();
    $cache->endDataCache(['data' => $data]);
    return $data;
}

Cache is invalidated on infoblock changes via BXClearCache(true, '/catalog/') in OnAfterIBlockElementUpdate.https://dev.1c-bitrix.ru/api_d7/bitrix/main/data/cache/

CORS and Deployment

We separate domains: api.yoursite.ru (Bitrix) and yoursite.ru (frontend). nginx CORS config:

location /api/ {
    add_header 'Access-Control-Allow-Origin' 'https://yoursite.ru';
    add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
    add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type';
    add_header 'Access-Control-Allow-Credentials' 'true';
    if ($request_method = 'OPTIONS') {
        return 204;
    }
    fastcgi_pass php-fpm;
}

We can also implement an API Gateway for Bitrix to aggregate multiple services.

Common pitfalls and solutions

Process and timelines

1. Site audit: infoblocks, integrations, load – 1–2 days.
2. API design: endpoint specs, data schemas – 2–3 days.
3. API and caching development: controllers, middleware, tests – 1–3 weeks.
4. Infrastructure: CORS, nginx, Redis, deployment – 2–3 days.
5. Frontend integration: joint testing – 1 week.

Typical project: 2–6 weeks. Cost is calculated individually after audit (starting at $5,000). Average project cost is $8,000–$15,000.

What's included

• Full API documentation (OpenAPI/Swagger).
• Source code: controllers, middleware, configurations.
• Caching and CORS setup on your server.
• Deployment and update instructions.
• Developer training (2 hours online).
• 2 weeks post-launch support.

Key benefits

Our team has over 10 years of Bitrix experience and 5 years in headless. We've implemented decoupled backend for 50+ projects, including catalogs with 200,000 items and loads of 10,000 requests/minute. Maintenance and new channel development savings reach 40% (average $2,000 per month). We guarantee stable API and complete documentation.

Request an audit of your project—we'll estimate timelines and cost in one day. Contact us for a consultation.