303  /  331

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

Просмотров: 1943 (Статистика ведётся с 06.02.2017)

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

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

  1. Регистрируется обработчик события OnRestServiceBuildDescription модуля rest. Обработчик возвращает массив вот такой структуры::
    return array(
       'имя_scope' => array(
          'имя_метода' => array(
             'callback' => обработчик_метода,
             'options' => array(),
          ),
          'имя_метода' => array(
             'callback' => обработчик_метода,
             'options' => array(),
          ),
       )
    );

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

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

    Обработчик метода - стандартный PHP псевдо-тип callback. Анонимные функции пока не поддерживаются.

  2. Функция-обработчик получит на вход 3 параметра:
    • ассоциативный массив данных вызова без авторизационных параметров;
    • параметр для возврата постранички (об этом ниже);
    • экземпляр класса \CRestServer, из которого получаются некоторые полезные данные.
  3. Функция-обработчик может:
    • либо вернуть ответ (массив или скалярное значение), которые будут приведены к json- или xml-виду,
    • либо бросить исключение, которое будет перехвачено и отображено в виде REST-ошибки.

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

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

    Пример:

    class RestTest
    {
       public static function OnRestServiceBuildDescription()
       {
          return array(
             'sigurdtest' => array(
                'sigurdtest.test' => array(
                   'callback' => array(__CLASS__, 'test'),
                   'options' => array(),
                ),
             )
          );
       }
    
       public static function test($query, $n, \CRestServer $server)
       {
          if($query['error'])
          {
             throw new \Bitrix\Rest\RestException(
                'Message',
                'ERROR_CODE',
                \CRestServer::STATUS_PAYMENT_REQUIRED
             );
          }
    
          return array('yourquery' => $query, 'myresponse' => 'My own response');
       }
    }
    
    AddEventHandler('rest', 'OnRestServiceBuildDescription', array('\RestTest', 'OnRestServiceBuildDescription'));

    http://cp.sigurd.bx/rest/sigurdtest.test?auth=qcdfzzjtp8hvcbjl42eg93wuw5n0mvsb&test=222
    
    HTTP/1.1 200 OK
    
    Content-Type: application/json; charset=utf-8
    
    {
        "result": {
           "myresponse": "My own response",  
           "yourquery": {
               "test": "222"
           }
       }
    }
    
    http://cp.sigurd.bx/rest/sigurdtest.test.xml?auth=qcdfzzjtp8hvcbjl42eg93wuw5n0mvsb&error=1
    
    HTTP/1.1 402 Payment Required
    
    Content-Type: text/xml; charset=utf-8
    
    <?xml version="1.0" ?>
    <response>
       <error>ERROR_CODE</error>
       <error_description>Message</error_description>
    </response>

Как определить обработчик отсутствующего в описании REST-метода "на лету"

Для этого используйте событие onFindMethodDescription, вызываемое перед отдачей ошибки METHOD_NOT_FOUND. Оно позволяет подставить описание метода "на лету".


1
Курсы разработаны в компании «1С-Битрикс»

Если вы нашли неточность в тексте, непонятное объяснение, пожалуйста, сообщите нам об этом в комментариях.
Развернуть комментарии