Как разработать REST API в собственном модуле для коробки Битрикс24

Как разработать REST API в собственном модуле для коробки Битрикс24

При разработке модулей для коробочной версии Битрикс24 иногда возникает необходимость дать возможность взаимодействовать с написанным модулем извне, это может быть облачное приложение, сторонний сайт, внешний сервис или другой модуль.

Существует три способа

Битрикс предоставляет три способа добавления своего REST API в модулях.

  • Добавить обработчик события «OnRestServiceBuildDescription» модуля «REST API», который позволяет задать разрешение для приложений и описать собственные API-методы, которые будут доступны этому разрешению.
  • Добавить обработчик события «onFindMethodDescription» модуля «REST API», который позволяет динамически генерировать API-методы, когда вызываемый API-метод не был найден.
  • Добавить собственный контроллер REST API по аналогии с добавлением AJAX-контроллеров.
  • Немного вводных

    Чтобы было максимально понятно, разбираться будем на примере. Предположим, что у нас есть модуль «bizprofi.randomizer».Создадим папку этого модуля. В этой папке создадим файл установки модуля «bizprofi.randomizer/install/index.php».

    Так же создадим пустой файл «bizprofi.randomizer/include.php». Его наличие — обязательное условие подключения модуля, без этого файла модуль не удастся подключить, не произойдет автозагрузка классов модуля, регистрация обработчиков событий и в итоге модуль работать не будет.

    Модуль должен уметь генерировать:
  • случайные числа — целые и с плавающей точкой
  • случайные строки — с заданным количеством символов
  • случайные предложения
  • Для тестирования будем использовать входящие вебхуки. Для этого создадим входящий вебхук и дадим ему разрешение «bizprofi:randomizer» (появится после реализации REST API). Запросы будем отправлять с помощью браузера, просто будем вбивать адрес запроса в адресную строку браузера.

    Адреса запроса имеют следующую структуру: «https://bitrix24.my.ru/rest/1/SecretToken/ApiMethod/», где «https://bitrix24.my.ru» — это адрес вашего Битрикс24. Цифра «1» — это идентификатор пользователя, который создал вебхук, «SecretToken» — код, который был присвоен созданному вебхуку, «ApiMethod» — метод API, который мы хотим вызвать.

    Нашему модулю нужно добавить 3 REST API-метода: случайные числа, случайные строки, случайные предложения.

    1. Получение одного случайного числа (bizprofi:randomizer.number.get)
    Можно указать тип числа: целое или с плавающей точкой. Для генерации используем \Bitrix\Main\Security\Random::getInt().

    Пример ответа при обращении к «https://bitrix24.my.ru/rest/1/SecretToken/bizprofi:randomizer.number.get/?type=int»

    Пример ответа при обращении к “https://bitrix24.my.ru/rest/1/SecretToken/bizprofi:randomizer.number.get/?type=float”

    2. Получение случайных чисел (bizprofi:randomizer.number.list)
    Можно указать тип числа: целое или с плавающей точкой и количество возвращаемых чисел, с постраничной навигацией чтобы было. Для генерации используем \Bitrix\Main\Security\Random::getInt().

    Пример ответа при обращении к «https://bitrix24.my.ru/rest/1/SecretToken/bizprofi:randomizer.number.list/?type=int&count=5»



    Пример ответа при обращении к “https://bitrix24.my.ru/rest/1/SecretToken/bizprofi:randomizer.number.list/?type=float&count=5”
    3. Получение одной случайной строки (bizprofi:randomizer.string.get)
    Можно указать количество символов в строке. Для генерации используем \Bitrix\Main\Security\Random::getString().

    Пример ответа при обращении к “https://bitrix24.my.ru/rest/1/SecretToken/bizprofi:randomizer.string.get/?length=15”
    4. Получение случайных строк (bizprofi:randomizer.string.list)
    Можно указать количество символов в строке и количество возвращаемых строк, с постраничной навигацией чтобы было. Для генерации используем \Bitrix\Main\Security\Random::getString().

    Пример ответа при обращении к “https://bitrix24.my.ru/rest/1/SecretToken/bizprofi:randomizer.string.list/?length=15&count=5”
    5. Получение одного случайного предложения (bizprofi:randomizer.text.get)
    Для генерации используем сервис FishText API.

    Пример ответа при обращении к “https://bitrix24.my.ru/rest/1/SecretToken/bizprofi:randomizer.text.get/”
    6. Получение случайных предложений (bizprofi:randomizer.text.list)
    Можно указать количество возвращаемых предложений, с постраничной навигацией чтобы было. Для генерации используем сервис FishText API.

    Пример ответа при обращении к “https://bitrix24.my.ru/rest/1/SecretToken/bizprofi:randomizer.text.list/?count=5”

    Разберем методы

    Теперь подробно рассмотрим каждый из методов реализации собственного REST API для модуля.


    1. Добавляем REST API через обработчик события «OnRestServiceBuildDescription»

    При установке модуля зарегистрируем обработчик события «OnRestServiceBuildDescription». Для этого в файле «bizprofi.randomizer/install/index.php» в методе «doInstall» после регистрации модуля добавим следующий код.


    При удалении модуля отменим регистрацию обработчика события «OnRestServiceBuildDescription». Для этого в файле «bizprofi.randomizer/install/index.php» в методе «doUninstall» перед отменой регистрации модуля добавим следующий код.


    После регистрации обработчика события создадим класс, который будет обрабатывать запросы REST API. Для этого создадим файл «bizprofi.randomizer/lib/rest/service.php», в котором объявим класс «\Bizprofi\Randomizer\Rest\Service».

    Осталось только описать доступные API-методы. Для этого для каждого типа случайных значений создадим отдельный сервис, который будет обрабатывать API-методы для данного типа.

    1. \Bizprofi\Randomizer\Rest\NumberService
    В файле «bizprofi.randomizer/lib/rest/numberservice.php» объявим класс «\Bizprofi\Randomizer\Rest\NumberService», который будет обрабатывать API-методы, связанные со случайными числами.

    2. \Bizprofi\Randomizer\Rest\StringService
    В файле «bizprofi.randomizer/lib/rest/stringservice.php» объявим класс «\Bizprofi\Randomizer\Rest\StringService», который будет обрабатывать API-методы, связанные со случайными строками.

    3. \Bizprofi\Randomizer\Rest\TextService
    В файле «bizprofi.randomizer/lib/rest/textservice.php» объявим класс «\Bizprofi\Randomizer\Rest\TextService», который будет обрабатывать API-методы, связанные со случайными предложениями.


    И в классе «\Bizprofi\Randomizer\Rest\Service» в методе «getDescription» для созданного разрешения перечислим все доступные API-методы.


    Теперь при обращении на REST API-методы, описанные выше, будут возвращаться рандомно сгенерированные данные.

    2. Добавляем REST API через обработчик события «onFindMethodDescription»

    Обработчик события «findMethodDescription» вызывается в момент, когда в REST API не найдено описание какого-то из методов. В обработчик события передается 2 параметра $method и $scope. На их основе обработчик может вернуть описание метода REST API. Мы будем использовать наработки из предыдущего примера.

    При установке модуля зарегистрируем обработчик события «onFindMethodDescription». Для этого в файле «bizprofi.randomizer/install/index.php» в методе «doInstall» после регистрации модуля добавим следующий код.



    При удалении модуля отменим регистрацию обработчика события «onFindMethodDescription». Для этого в файле «bizprofi.randomizer/install/index.php» в методе «doUninstall» перед отменой регистрации модуля добавим следующий код.


    В классе «\Bizprofi\Randomizer\Rest\Service» объявим метод «onFindMethodDescription»


    Теперь мы имеем полностью идентичное предыдущему примеру API за одним исключением — REST API-метод «methods» будет возвращать пустой результат для разрешения «bizprofi:randomizer».

    3. Добавляем REST API через контроллеры модуля

    В последней версии ядра (сейчас это вресия 18.1.8) появилась возможность добавлять REST API-методы через контроллеры. Этот вариант ещё не задокументирован, но уже работает.

    При использовании этого метода нужно иметь ввиду, что после очередного обновления ядра может что-то измениться. Для добавления REST API-методов через контроллеры необходимо создать файл «.settings.php» в папке модуля. Файл должен вернуть массив следующей структуры.

    После этого необходимо создать сами контроллеры, которые будут обрабатывать запросы к api. Поступим так же как в первом примере, для каждого типа случайных значений создадим собственных контроллер.

    1. \Bizprofi\Randomizer\Rest\Controller\Number
    В файле «bizprofi.randomizer/lib/rest/controller/number.php» объявим класс «\Bizprofi\Randomizer\Rest\Controller\Number», который будет обрабатывать API-методы, связанные со случайными числами.

    2. \Bizprofi\Randomizer\Rest\Controller\Line
    Имя «string» зарезервированно, и мы не можем создать класс с таким именем, поэтому используем «line». В файле «bizprofi.randomizer/lib/rest/controller/line.php» объявим класс «\Bizprofi\Randomizer\Rest\Controller\Line», который будет обрабатывать API-методы, связанные со случайными строками.

    3. \Bizprofi\Randomizer\Rest\Controller\Text
    В файле «bizprofi.randomizer/lib/rest/controller/text.php» объявим класс «\Bizprofi\Randomizer\Rest\Controller\Text», который будет обрабатывать API-методы, связанные со случайными предложениями.

    Теперь мы имеем API-методы следующей структуры «bizprofi:randomizer.text.get», где «bizprofi» — имя вендора, «randomizer» — имя модуля, «text» — имя контроллера, а «get» — имя метода. REST API, добавленное таким способом функционально ничем не отличается от REST API добавленного вторым способом.

    Итог

    Мы описали три способа добавления REST API. Все три способа имеют один и тот же результат особой разницы между ними нет. Я рекомендую использовать первый. У второго способа чуть более ограниченный функционал, а третий пока еще не стабилен. Также можно почитать главу по добавлению собственного REST API в курсе компании «1С-Битрикс» — Разработчик Bitrix Framework.
    Эмиль Алиев
    Эмиль Алиев
    Ведущий разработчик Битрикс24