Организация API + REST

Классы и методы

В модуле используется один единственный класс для работы - \Bxmaker\Api\Handler. Для инициализации модуля необходимо его подключить и вызвать соответствующие методы, как на примере.

if(\Bitrix\Main\Loader::includeModule('bxmaker.api')){
    
    $oApi = \Bxmaker\Api\Handler::getInstance();
    $oApi->setParam(array(
        'IBLOCK_ID_CATALOG' => 3,
        'IBLOCK_ID_OFFER' => 4,
    ));

    $oApi->setSkipMethodSessidControl(array(
         'data.idea',          
    ));

      $oApi->init();
      $oApi->showResult();

}
else
{

    /* используется как заглушка, чтобы не нарушать работу клиентской части сайта в случае если модуль не установлен */
    json_encode(array('error' => array(
      'error_code' => 0,
      'error_msg' => 'Модуль обработки запросов не установлен'
    )));
}

setParam

Метод setParam() необходимо вызывать сразу после получения объекта класса. На входе он принимает массив параметров, которые затем можно получить в обработчике с помощью метода getParam().

/* установка */
$oApi->setParam(array( 
   'IBLOCK_ID_CATALOG' => 3,
    'IBLOCK_ID_OFFER' => 4,
   'PROIZVOLNYE_IMENA' => true
));

/* получение в файле обработчика */ 
if($this->getParam('PROIZVOLNYE_IMENA))
{
   //... какие-то действия
}

getParam

Метод getParam() используется в обработчиках AJAX запросов, например в файле из примера - /api/sale/add2_basket.php

<?if (!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED !== true) { 
    die();
} 

if($this->getParam('PROIZVOLNYE_IMENA))
{
    
}
//... какие-то действия
//...

init

Метод init() используется для обработки поступившего запроса, поиска соответствующего обработчика и подготовки результата выполнения. Вызывается в файле /api/index.php.

Соответственно все запросы ajax нужно производить к url адресу /api/. Модуль уже сам подключит необходимый обработчики запроса исходя из значения в параметре запроса method. 

$oApi->init();

setSkipMethodSessidControl

Метод позаволяет отключить для некоторых или для всех методов проверку сесии, в частности проверку обязательного парамтера sessid - необходимого для обеспечения безопасности. Метод вызывается при инициализации класса обработчика ajax запросов в файле /api/index.php. Вызывать метод необходимо до вызова init().

На входе нужно указать массив методов, или групп методов. Группа методов обозначается звездочкой - status.work.*. Соответственно не будет проверяться sessid для любых методов входящих в группу, например status.work.log, status.work.import, и тд. * - любое сочетание символов, кроме точки.

$oApi->setSkipMethodSessidControl(array(
         'data.idea.*',
         'data.mix'
    ));

setJsonEncodeOptions

Метод setJsonEncodeOptions позволяет указать битовую маску из флагов передаваемых функции json_encode. Это позволяет менять итоговое представление закодированных данных.

Например чтобы получить читаемый вариант ответа можно сделать так


$oApi->setJsonEncodeOptions(JSON_UNESCAPED_UNICODE|JSON_HEX_TAG|JSON_HEX_AMP|JSON_HEX_APOS|JSON_HEX_QUOT);

showResult

Метод showResult() используется для вывода результата обработки запроса в json формате.

$oApi->showResult();

Обычный ответ 

{ 
    "response" : { 
        "msg" : "Товар успешно добавлен в корзину" 
    } 
}

Ответ с ошибкой 

{ 
    "error": { 
        "msg": "Ваша сессия закончилась, обновите страницу и попробуйте снова.", 
        "code": "/api/1", 
        "more": [] 
    }, 
    "errors": [ 
       { 
           "msg": "Ваша сессия закончилась, обновите страницу и попробуйте снова.", 
            "code": "/api/1", 
            "more": [] 
       } 
    ] 
}

get

Метод get() используется для получения параметров запроса. Например при формировании AJAX запроса был указан параметр name=Василий, для получения его значения в обработчике используется следующий код, при этом у значения по краям обрезаются пробелы. В случае если значения для параметра не получено, то возвращается null

if (!$this->get('name') || strlen($this->get('name')) < 0) {
    return $this->setError('Не указано Имя!', '1');
}

setResult

Метод setResult() используется в обработчике соответствующего метода запроса, для установки результата выполнения операции. На входе принимает массив, содержание которого может быть произвольным. Если вызывается несколько раз, то получаемый массив будет слит рекурсивно с уже имеющимся результатом выполнения операции.

$this->setResult(array( 
    'success' => true ,
   'msg' => 'Операция выполнена успешно'
));

setError

Метод setError() используется для фиксирования ошибок выполнения запросов к API, и принимает на вход 3 параметра - Текст ошибки, код ошибки, и дополнительный массив данных для ответа, например может содержать новый идентификатор капчи. В ответе к кодам ошибки добавляется префикс обработчика, например указан был код - 1, в ответе модуля код ошибки будет иметь вид /api/sale/add2_basket/1.

return $this->setError('Не удалось удалось сохранить изменения!', '4');
return $this->setError('Не удалось удалось сохранить изменения!', '4', array(
    'captcha_sid' => 's1nh55h98g626268768sfof'
));
Краткая информация
Примеры