Создание API

Хаки могут предоставлять новые приложения для работы API или расширять существующие новыми функциями. Перезапись существующих функций в приложениях не поддерживается.

Подготовка файла с API

Файлы с API-функциями размещаются в папке модулей. На каждое "приложение" для API создаётся свой файл. Все функции приложения размещаются в одном файле.

Название файла должно начинаться с api и названия приложения через дефис, например: api-proxy.php. Название приложения может содержать только маленькие латинские символы и цифры. Название приложения может начинаться как с буквы, так и с цифры. Запрещается использование заглавных букв и символов, в том числе дефиса и знака подчёркивания.

Особенности создания функций

Все функции, отвечающие за работу API, должны иметь особое название: api_app_func, где app - название приложения, а func - название функции. К названию функции предъявляются те же требования, что и к названию приложения.

Адрес доступа функции формируется из ключевого слова api, названия приложения и названия самой функции. Через точку указывается формат результата. Например, функция может называться api_proxy_check, тогда она будет доступна по адресу api/proxy/check.json.

Важно! Вы не можете создавать функции с именами уже имеющихся системных функций. Переписывание системных API-функций недоступно.

API-функция всегда принимает два параметра - ядро и идентификатор пользователя, который вызвал функцию. Функция должна возвращать массив с результатами выполнения. Рекомендуется использовать в массиве поле status, которое принимает значение error в случае ошибки и ok в случае успешного выполнения. Код ошибки принято отдавать в поле error.

Пример оформления функции:

function api_proxy_check( $core, $user ) {
 $uid = (int) $core->get['uid'];
 if ( $$core->hack->proxyland->check( $uid ) ) {
   return [ 'status' => 'ok', 'id' => $uid ];
 } else return [ 'status' => 'error', 'error' => 'failed' ];
}

Параметр $user передаётся в функцию даже в том случае, если у неё отключена авторизация. Рекомендуется всегда включать авторизацию для функций.

Подключение функций к системе

Подключение API-приложений к системе выполняется через ключ api массива инициализации хака. В качестве значения указывается массив строк с названиями приложений. Если ваш файл называется app-proxy.php, то в качестве значения в массиве указывается proxy.

Например, приложение proxy подключается так:

'api' => [ 'proxy' ],

Рекомендуется включать авторизацию для всех создаваемых API-функций. За авторизацию отвечает ключ api-auth в массиве инициализации хака. На каждое приложение используется свой массив. Первым элементом указывается название приложения. Вторым элементом указывается массив строк с названиями функций. Если функция только одна, можно указать её строкой, а не массивом.

Например, так будет обязательна авторизация для функций check и add приложения proxy и функции getproxy приложения wm:

'api-auth' => [
  [ 'proxy', [ 'check', 'add' ] ],
  [ 'wm', 'getproxy' ],
],

Рассмотрим полный пример подключения API в файле start.php. Мы подключаем новое приложение proxy, которое содержит функции check, add, del, edit и list. Также мы добавляем новую функцию getproxy в системное приложение wm. Все функции требуют авторизации.

return [
  /* … здесь идут настройки других элементов … */
  'api' => [ 'proxy', 'wm' ],
  'api-auth' => [
    [ 'proxy', [ 'check', 'add', 'del', 'edit', 'list' ] ],
    [ 'wm', 'getproxy' ],
  ],
];