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 рішення.