Добавление своих методов в REST API

OnRestServiceBuildDescription системное событие в REST API Битрикс24, которое позволяет добавить собственные REST методы в коробочной версии платформы.

Принцип работы

Принцип работы события OnRestServiceBuildDescription:

Регистрация

В своём модуле вы подключаетесь к системному событию OnRestServiceBuildDescription. Через него объявляете новый scope или логическую группу и список собственных методов.

Описание

Для каждого метода указываете человекочитаемое название и указывается, какой внутренний PHP-обработчик отвечает за логику.

Появление в документации

После сохранения изменений и очистки кэша, портал автоматически включает новые методы в общий список API. Внутренние и сторонние приложения смогут запрашивать права на новый scope и вызывать ваш метод также, как штатные команды по обычному REST адресу.

Порядок действий

Регистрируется обработчик события OnRestServiceBuildDescription модуля rest через метод добавления событий registerEventHandler или AddEventHandler. Обработчик возвращает массив вот такой структуры:

return array(
    'имя_scope' => array(
        'имя_метода' => array(
            'callback' => обработчик_метода,
            'options' => array(),
        ),
        'имя_метода' => array(
            'callback' => обработчик_метода,
            'options' => array(),
        ),
    )
);

Имя scope произвольное, если регистрируется собственный scope, то он будет доступен в списке разрешений для локальных приложений. Для добавления методов в существующий scope, укажите имя метода. Если добавляются методы, доступные всем приложениям, то вместо имени указывается константа \CRestUtil::GLOBAL_SCOPE.

Имя метода произвольное, допускается использование как верхнего, так и нижнего регистра. Но рекомендуется придерживаться нижнего регистра и традиционного именования имя_scope.имя_сущности.действие.

Обработчик метода, стандартный callback который должен получить на вход 3 параметра:

Ассоциативный массив данных вызова без авторизационных параметров
Параметр для возврата постранички
Экземпляр класса \CRestServer, из которого получаются некоторые полезные данные

Обработчик метода, стандартный callback может:

Вернуть ответ в виде массива или скалярного значения, которые будут приведены к json или xml виду
Бросить исключение, которое будет перехвачено и отображено в виде REST ошибки

Если требуется указать HTTP статус ошибки, то воспользуйтесь классом \Bitrix\Rest\RestException. Если при этом ранее ядром было сгенерировано старое исключение $APPLICATION->ThrowException(), оно перезапишет ошибку в ответе.

К моменту вызова функции-обработчика, проверка прав доступа уже выполнена, объект $USER уже проинициализирован с авторизацией привязанного к токену пользователя.

init.phpclass RestTest
{
    public static function OnRestServiceBuildDescription()
    {
        return array(
            'hmarketing' => array(
                'hmarketing.test' => array(
                    'callback' => array(__CLASS__, 'test'),
                    'options' => array(),
                ),
            )
        );
    }

    public static function test($query, $navStart, \CRestServer $server)
    {
        if ($query['error']) {
            throw new \Bitrix\Rest\RestException(
                'Message',
                'ERROR_CODE',
                \CRestServer::STATUS_PAYMENT_REQUIRED
            );
        }

        return array(
            'yourquery' => $query,
            'myresponse' => 'Мой собственный ответ'
        );
    }
}

AddEventHandler(
    'rest',
    'OnRestServiceBuildDescription',
    array(
        '\RestTest',
        'OnRestServiceBuildDescription'
    )
);