Свой REST API на 1С-Битрикс через Controller D7

Мобильное приложение, внешняя интеграция или SPA-фронтенд, работающий с данными сайта, — всем им нужен API. Разберём, как реализовать собственный REST-эндпоинт на 1С-Битрикс через штатный механизм контроллеров D7, а не через самописную маршрутизацию с нуля.

Контроллер как основа REST-эндпоинта

<?php

namespace Vendor\Module\Controller;

use Bitrix\Main\Engine\Controller;
use Bitrix\Main\Engine\ActionFilter;

class Product extends Controller
{
    public function configureActions(): array
    {
        return [
            'list' => [
                'prefilters' => [
                    new ActionFilter\Authentication(),
                ],
            ],
        ];
    }

    public function listAction(int $sectionId = 0): array
    {
        $items = getProductsBySection($sectionId);

        return ['items' => $items];
    }
}

Класс, унаследованный от Controller, автоматически становится доступен по URL вида /rest/module_name/product.list/ без ручной настройки маршрутизации — метод, оканчивающийся на Action, превращается в отдельный эндпоинт, а фреймворк сам берёт на себя сериализацию ответа в JSON и разбор параметров запроса.

Обязательная авторизация для закрытых данных

Фильтр ActionFilter\Authentication в примере выше требует авторизованного пользователя для доступа к действию — без явного добавления такого фильтра эндпоинт по умолчанию доступен анонимно, что уместно только для действительно публичных данных. Для эндпоинтов, отдающих чувствительные данные (заказы конкретного пользователя, персональные данные), фильтр авторизации обязателен.

Нужна помощь с Битрикс?

Валидация входных параметров

<?php

public function configureActions(): array
{
    return [
        'list' => [
            'prefilters' => [
                new ActionFilter\Authentication(),
            ],
        ],
    ];
}

public function listAction(int $sectionId): array
{
    if ($sectionId <= 0) {
        $this->addError(new \Bitrix\Main\Error('Некорректный ID раздела'));

        return [];
    }

    // ...
}

Типизация параметров метода (int $sectionId) даёт базовую проверку типа автоматически, но не заменяет проверку допустимости самого значения — отрицательный или несуществующий ID раздела технически проходит проверку типа, но не является корректным входным значением, что требует явной дополнительной проверки внутри метода действия.

Обработка ошибок через объект результата

<?php

public function createAction(string $name, float $price): array
{
    if (empty($name)) {
        $this->addError(new \Bitrix\Main\Error('Название обязательно', 'EMPTY_NAME'));
    }

    if ($price <= 0) {
        $this->addError(new \Bitrix\Main\Error('Цена должна быть положительной', 'INVALID_PRICE'));
    }

    if ($this->getErrors()) {
        return null;
    }

    // ... создание записи ...
}

Метод addError добавляет ошибку в общий список результата действия — фреймворк сам формирует корректный формат ответа с описанием ошибок, если они были добавлены, без необходимости вручную формировать структуру ответа об ошибке на каждый отдельный сценарий валидации.

CORS для доступа с другого домена

Если API должен быть доступен фронтенду на другом домене (например, отдельно развёрнутое SPA-приложение), требуется явная настройка CORS-заголовков — без неё браузер блокирует межсайтовые запросы к API политикой same-origin по умолчанию, и это не связано напрямую с логикой самого контроллера, а требует отдельной настройки на уровне обработки запроса.

Ограничение частоты запросов к публичным эндпоинтам

Публично доступный эндпоинт без ограничения частоты запросов уязвим для злоупотребления — массового автоматического сбора данных или паразитной нагрузки на сервер. Для таких эндпоинтов стоит предусмотреть лимит запросов с одного IP-адреса или API-ключа за период времени, аналогично защите обычных публичных форм сайта.

Частые ошибки

Эндпоинт с чувствительными данными доступен без авторизации. Фильтр Authentication не добавлен по умолчанию, доступ открыт анонимно.
Валидация ограничена только типизацией параметра. Технически корректный тип, но недопустимое значение проходит без проверки.
Нет ограничения частоты запросов на публичном эндпоинте. Уязвимость для автоматического злоупотребления.

Итог

Штатный механизм контроллеров D7 закрывает большую часть работы по созданию REST-эндпоинта — маршрутизацию, сериализацию ответа, единый формат ошибок — оставляя разработчику только бизнес-логику и явную настройку авторизации там, где она нужна. Валидация входных значений сверх базовой типизации и ограничение частоты запросов для публичных эндпоинтов остаются на стороне разработчика и не настраиваются автоматически.

Теги: D7 Разработка