При создании собственных приложений для коробочных редакций возникает потребность в добавлении новых методов для них в 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. Оно позволяет подставить описание метода "на лету".

Как работать с навигацией в своих методах реста

\Bitrix\Main\Loader::includeModule('rest');
class ApiTest extends \IRestService
{
	public static function OnRestServiceBuildDescription()
	{
		return array(
			'apitest' => array(
				'api.test.list' => array(
					'callback' => array(__CLASS__, 'getList'),
					'options' => array(),
				),
			)
		);
	}

	public static function getList($query, $nav, \CRestServer $server)
	{
		$navData = static::getNavData($nav, true);

		$res = \Bitrix\Main\UserTable::getList(
			[
				'filter' => $query['filter']?:[],
				'select' => $query['select']?:['*'],
				'order' => $query['order']?:['ID' => 'ASC'],
				'limit' => $navData['limit'],
				'offset' => $navData['offset'],
				'count_total' => true,
			]
		);

	$result = array();
	while($user = $res->fetch())
	{
		$result[] = $user;
	}

	return static::setNavData(
		$result,
		array(
			"count" => $res->getCount(),
			"offset" => $navData['offset']
		)
	);
	}
}

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

На примере ORM-класса работы с пользователями показывается как зарегистрировать свой метод для работы с таблицами пользователей. Если вам необходимо сделать постраничную навигацию для методов не ORM-классов, например, для getNavData(), то вторым параметром передайте: false ($navData = static::getNavData($nav, false);), тогда вернётся навигация соответствующая методам старого ядра.

Пример запроса:

/rest/api.test.list?order[ID]=ASC&filter[<ID]=1000&select[]=ID&select[]=NAME&start=200