API-first на 1С-Битрикс: REST, OAuth, кеширование под ключ

Клиент пришёл с задачей: интернет-магазин на Битрикс, фронтенд на React, мобильное приложение iOS/Android, интеграция с 1С. Классические компоненты не подходят — нужен JSON. Мы разработали API-first архитектуру: Битрикс стал бэкендом, отдающим данные через REST API. Фронтенд-команда работает с контрактом, не зная про инфоблоки. Результат — средняя экономия на поддержке 35% за счёт единого API-контракта, а время вывода новых фич на мобильные платформы сократилось в 2–3 раза. Мы специализируемся на таких решениях более 10 лет. На счету — 50+ проектов, где Битрикс выступает как API-сервер. Оценим ваш проект бесплатно. Среднее время ответа API — 80 мс при пиковой нагрузке до 5000 RPS. Свяжитесь с нами для бесплатной оценки проекта.

API-first vs классический Битрикс: в чём разница?

API-first радикально отличается от классической разработки. Компонент bitrix:catalog.section рендерит HTML на сервере. API-подход отдаёт JSON — фронтенд управляет отрисовкой. Это даёт:

• В 2–3 раза более быструю разработку мобильных приложений по сравнению с классическим подходом.
• Единую точку интеграции для всех клиентов: веб, iOS, Android, B2B-партнёры.
• Полный контроль над фронтендом: React/Vue SPA с SSR, Swift, Kotlin.

Когда API-first оправдан?

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

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

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

Как обеспечить производительность API?

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

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

Ключевые технические решения

Архитектура

Клиенты ├── 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. Согласно документации 1С-Битрикс, это стандартный путь.

// /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).

API Key для B2B-партнёров с фиксированным IP.

Как версионировать API без боли?

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

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

Все эндпоинты документируются в формате OpenAPI 3.0. Фронтенд-команда генерирует типизированный клиент (TypeScript SDK, Swift/Kotlin клиенты), тест-инженеры автоматизируют тестирование по спецификации.

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

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

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

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

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

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

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

Процесс работы

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

• Проектирование API: ресурсы, эндпоинты, OpenAPI-спецификация.
• Разработка REST-эндпоинтов с авторизацией и кешированием.
• Документация Swagger UI с примерами запросов.
• Интеграционное тестирование.
• Передача исходного кода, инструкций по деплою, доступов.
• Обучение вашей команды работе с API.
• Поддержка на этапе запуска.

Как за 5 шагов реализовать REST-эндпоинт

1. Определить ресурс и эндпоинты (например, /api/v1/catalog/products).
2. Создать класс-обработчик с методами list, get, create, update, delete.
3. Зарегистрировать эндпоинт через событие OnRestServiceBuildDescription.
4. Добавить авторизацию (OAuth, JWT, API Key).
5. Протестировать через Swagger UI и contract-тесты.

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

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