REST API на 1С-Битрикс: проектирование, реализация, документация

Битрикс имеет встроенный REST API для Битрикс24, но для сайта на «1С-Битрикс: Управление сайтом» собственного REST нет — его нужно строить. Задача возникает регулярно: мобильное приложение требует данные каталога, сторонний сервис хочет получать заказы, фронтенд на React или Vue нужно снабжать данными без перезагрузки страницы. Типичная боль: при каждом новом интеграторе приходится писать костыли на COption::GetOptionString и выводить JSON через echo json_encode(), а через месяц код превращается в «лапшу».

У нас за плечами 10+ лет опыта Битрикс-разработки и более 50 реализованных API-интеграций, обрабатывающих до 10 000 RPS. Знаем все подводные камни: от проблем с кэшированием инфоблоков до ошибок сериализации в ORM. Гарантируем стабильную работу под нагрузкой и предоставляем документацию Swagger для каждого эндпоинта. Средняя экономия времени на интеграцию с внешними сервисами составляет 40%.

Как построить REST API на D7?

Основа API — контроллеры на базе \Bitrix\Main\Engine\Controller. Каждый контроллер отвечает за один ресурс. Сравнение с самописными решениями: D7-контроллеры автоматически обрабатывают ошибки, сериализуют ответы в JSON и поддерживают префильтры. Это в 2–3 раза сокращает объём кода по сравнению с ручной обработкой через $APPLICATION->RestartBuffer().

1. Создайте модуль в /local/modules/ с структурой my.api. Определите install/index.php с методами InstallDB() и UnInstallDB() для создания таблиц.
2. Регистрируйте контроллеры в routes.php (начиная с ядра 20.0). Сопоставьте URL с классами, например 'api/v1/products' => 'MyApi\Controllers\ProductController'.
3. Реализуйте action-методы. Каждый метод возвращает массив — ядро сериализует его в JSON. Добавьте префильтры для аутентификации и ограничения HTTP-методов.
4. Подключите сервис-слой — вынесите логику выборки и обработки в отдельные классы ProductService, OrderService и т.д. Это упрощает юнит-тестирование.
5. Документируйте эндпоинты через Swagger (OpenAPI 3.0). Генерируйте спецификацию из аннотаций или вручную. Разместите Swagger UI в /local/swagger/.

/local/modules/my.api/lib/
├── Controllers/
│   ├── ProductController.php    → GET /api/v1/products
│   ├── OrderController.php      → GET/POST /api/v1/orders
│   ├── CategoryController.php   → GET /api/v1/categories
│   └── AuthController.php       → POST /api/v1/auth/token
├── Services/
│   ├── ProductService.php
│   └── OrderService.php
├── Transformers/
│   ├── ProductTransformer.php   → форматирование ответа
│   └── OrderTransformer.php
└── Middleware/
    ├── AuthMiddleware.php
    └── RateLimitMiddleware.php

Пример контроллера: метод listAction принимает параметры пагинации и возвращает данные с мета-информацией. Код короткий, без лишних проверок — всё встроено в D7.

namespace MyApi\Controllers;

use Bitrix\Main\Engine\Controller;
use Bitrix\Main\Engine\ActionFilter;
use MyApi\Services\ProductService;
use MyApi\Middleware\AuthMiddleware;

class ProductController extends Controller
{
    public function configureActions(): array
    {
        return [
            'list'   => ['prefilters' => [new AuthMiddleware()]],
            'detail' => ['prefilters' => [new AuthMiddleware()]],
            'create' => ['prefilters' => [new AuthMiddleware(), new ActionFilter\HttpMethod(['POST'])]],
        ];
    }

    public function listAction(int $page = 1, int $perPage = 20, string $category = ''): array
    {
        $service = new ProductService();
        $result  = $service->getList($page, $perPage, $category);

        return [
            'data'  => $result['items'],
            'meta'  => [
                'total'    => $result['total'],
                'page'     => $page,
                'per_page' => $perPage,
                'pages'    => ceil($result['total'] / $perPage),
            ],
        ];
    }

    public function detailAction(int $id): array
    {
        $service = new ProductService();
        $product = $service->getById($id);

        if (!$product) {
            $this->addError(new \Bitrix\Main\Error('Товар не найден', 404));
            return [];
        }

        return ['data' => $product];
    }
}

Как обеспечить безопасность REST API?

Аутентификация — частый источник проблем. Для server-to-server используем API-ключи: простой заголовок X-Api-Key. Для пользовательских запросов (mobile app, SPA) — JWT. Библиотека firebase/php-jwt подключается через Composer. Refresh-токены сохраняем в кастомной ORM-таблице с привязкой к пользователю. Это надёжнее, чем хранить сессии в файлах.

Подробнее о JWT: JSON Web Token (Wikipedia).

Формат ответов — консистентность важна. Мы придерживаемся единого шаблона: status, data, meta для успеха, errors для ошибок. D7-контроллер формирует ответ автоматически, но мы переопределяем processAfterAction для полного контроля.

protected function processAfterAction(Action $action, $result)
{
    $response = \Bitrix\Main\Application::getInstance()->getContext()->getResponse();
    $response->addHeader('Content-Type', 'application/json; charset=utf-8');

    if ($this->getErrors()) {
        echo json_encode([
            'status' => 'error',
            'errors' => array_map(fn($e) => [
                'code'    => $e->getCode(),
                'message' => $e->getMessage(),
            ], $this->getErrors()),
        ], JSON_UNESCAPED_UNICODE);
    } else {
        echo json_encode([
            'status' => 'ok',
            'data'   => $result,
        ], JSON_UNESCAPED_UNICODE);
    }

    exit;
}

CORS — если API вызывается с другого домена, обязательно добавляем заголовки и обрабатываем OPTIONS-запросы. Иначе браузер блокирует запросы.

Rate limiting — защита от перегрузок. Используем Redis или, для малой нагрузки, b_option. Например, 1000 запросов в час на ключ.

Как протестировать API?

Пишите интеграционные тесты на PHPUnit. Для изоляции используйте SQLite вместо MySQL. Проверяйте не только успешные сценарии, но и граничные случаи: неверные параметры, отсутствующие ресурсы, превышение лимитов. Пример теста для listAction:

public function testListReturnsPaginationMeta(): void
{
    $controller = new ProductController();
    $result = $controller->listAction(1, 10);
    $this->assertArrayHasKey('meta', $result);
    $this->assertArrayHasKey('total', $result['meta']);
}

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

Мы не просто пишем код. Каждый проект включает:

• Техническое задание с прототипом эндпоинтов.
• Архитектурную схему модуля.
• Реализацию контроллеров, сервисов, трансформеров.
• Документацию OpenAPI 3.0 (Swagger).
• Настройку rate limiting и CORS.
• Инструкцию по деплою и поддержку в течение месяца.

Сроки ориентировочно

REST API на Битрикс строится из стандартных блоков — контроллеры, ORM, кеш. Сложность не в технологии, а в проектировании: правильные эндпоинты, консистентные форматы ответов, обработка граничных случаев. Если вам нужен надёжный REST API для вашего сайта на Битрикс, свяжитесь с нами — мы оценим ваш проект за один день. Закажите разработку REST API и получите готовую документацию Swagger в комплекте.

Официальная документация Битрикс D7