Разработка API-first решения на 1С-Битрикс

Разработка API-first решения на 1С-Битрикс

API-first — это подход, при котором Битрикс выступает бэкендом с REST API, а фронтенд (сайт, мобильное приложение, сторонние системы) работает через этот API. Нет тесной связи PHP-шаблонов с логикой. Нет серверного рендеринга страниц через компоненты. Есть чистый API: получил запрос, вернул JSON, фронтенд отрисовал.

Это радикально отличается от классической разработки на Битрикс, где компонент bitrix:catalog.section рендерит HTML прямо на сервере. API-first используют, когда нужно одновременно работать с несколькими клиентами: веб-сайт на React/Vue, мобильное приложение iOS/Android, B2B-кабинет — всё через один API.

Когда это оправдано

API-first на Битрикс имеет смысл, если:

• Параллельно существуют несколько фронтенд-клиентов с одной бизнес-логикой
• Нужен полный контроль над фронтендом (React/Vue SPA с SSR)
• Мобильное приложение — полноценная часть продукта, не дополнение
• Предполагается интеграция с большим числом внешних систем через единую точку входа

Если это просто сайт без мобильного приложения — API-first избыточен.

Архитектура

Битрикс в API-first роли — это уровень бизнес-логики и хранилище данных. Модули catalog, sale, iblock продолжают работать, но к ним обращаются не через компоненты, а через API-слой.

Клиенты
 ├── React SPA (веб)
 ├── React Native / Swift / Kotlin (мобайл)
 └── Внешние системы (B2B-партнёры, ERP)
         ↓ HTTPS/JSON
   API-слой (custom REST endpoints на Битрикс)
         ↓
   Бизнес-логика (модули catalog, sale, iblock, custom)
         ↓
   База данных (MySQL/PostgreSQL)

Реализация REST-эндпоинтов

В Битрикс24 и 1С-Битрикс (коробка) есть механизм регистрации кастомных REST-методов через событие OnRestServiceBuildDescription. Это стандартный путь для коробочной версии:

// /local/modules/vendor.api/lib/resthandler.php
class RestHandler
{
    public static function onRestServiceBuildDescription(): array
    {
        return [
            'vendor' => [
                'catalog.product.list' => [
                    'callback' => [self::class, 'getCatalogProducts'],
                    'options' => ['private' => false],
                ],
                'catalog.product.get' => [
                    'callback' => [self::class, 'getCatalogProduct'],
                    'options' => ['private' => false],
                ],
                'sale.order.create' => [
                    'callback' => [self::class, 'createOrder'],
                    'options' => ['private' => false],
                ],
            ],
        ];
    }
}

Альтернатива — компонент-контроллер на отдельном URL (/api/v1/), который принимает запросы без использования механизма REST Битрикс. Это даёт полный контроль над роутингом и форматом ответа, но выпадает из стандартной инфраструктуры авторизации.

Авторизация API-клиентов

OAuth 2.0. Стандартный путь для публичного API. Клиент получает access_token через Authorization Code или Client Credentials flow. Токены хранятся в b_oauth_access_token. Битрикс поддерживает OAuth из коробки через модуль oauth.

JWT. Для server-to-server и мобильных клиентов. Сервер подписывает JWT собственным ключом, клиент передаёт в заголовке Authorization: Bearer. Проверяем на каждом запросе — без обращения к БД (stateless). Реализуется как middleware перед роутером.

API Key. Для B2B-партнёров с фиксированным IP. Простота в реализации, но нет механизма ротации без участия администратора.

Кеширование на уровне API

Без кеширования API-сервер превращается в источник нагрузки: каждый хит мобильного приложения — это N запросов к БД. Стратегия:

• HTTP-кеш (Cache-Control: max-age=300, ETag): для публичных ресурсов (каталог, статьи). CDN кеширует на своей стороне.
• Redis/Memcached: сложные агрегированные ответы (страница товара = данные из iblock + цены из catalog + остатки + отзывы). TTL 5–15 минут, инвалидация по тегу при изменении данных.
• Тегированный кеш Битрикс: \Bitrix\Main\Data\TaggedCache — инвалидируем кеш конкретного товара при его обновлении через 1С-обмен.

Версионирование API

Версионирование обязательно — клиент не обновляется мгновенно. Мобильное приложение на iPhone у пользователя — версия полугодовой давности. Нельзя сломать контракт.

Схема: /api/v1/catalog/products, /api/v2/catalog/products. v1 и v2 живут параллельно. v1 объявляется deprecated с датой отключения, которую сообщают клиентам через Deprecation и Sunset заголовки.

OpenAPI-спецификация

Все эндпоинты документируются в формате OpenAPI 3.0. Это не роскошь — это инструмент: фронтенд-команда генерирует типизированный клиент (TypeScript SDK, Swift/Kotlin клиенты), тест-инженеры автоматизируют тестирование по спецификации. Спецификация хранится в репозитории вместе с кодом и обновляется при каждом изменении API.

Обработка ошибок

Единый формат ошибок для всех эндпоинтов:

{
  "error": {
    "code": "PRODUCT_NOT_FOUND",
    "message": "Товар с ID 12345 не найден",
    "details": {}
  }
}

HTTP-коды используются семантически: 404 — не найден, 422 — ошибка валидации, 429 — превышен лимит, 503 — сервис временно недоступен.

Тестирование

API без тестов — API без доверия. Покрываем:

• Unit-тесты на бизнес-логику обработчиков
• Integration-тесты на эндпоинты (PHPUnit + реальная тестовая БД)
• Contract-тесты — проверяем, что ответ соответствует OpenAPI-схеме (Dredd, Schemathesis)

Этапы разработки

API-first на Битрикс — это дополнительный слой абстракции, который требует дисциплины команды. Зато фронтенд-разработчики работают с чистым JSON-контрактом и не знают ничего о компонентах и инфоблоках.