API

KodiCMS предоставляет возможность программными средствами получать и записывать данные через REST API.

Для доступа к API контроллерам со стороннего сайта необходим ключ доступа (должен быть передан в AJAX запросе с ключом api_key), который генерируется при установке системы и указан на странице настроек API

---

Расположение API контроллеров начинается относительно папки classes\controller\api и иметь любую глубину расположения файла класса контроллера. Все контроллеры должны наследовать системный контроллер Controller_System_API URL для доступа к контроллеру строится следующим образом.

/api</directory>-controller<.action>/<param>, значения указанные в треугольных скобках являются не обязательными.

Пример построения ссылок доступа к контроллерам.

classes\controller\api
	|
	pages\tags.php // /api/pages-tags
	|
	users.php // /api-users
	|
	users\roles.php // /api/users-roles
	|
	datasource\section\headline.php // /api/datasource/section.headline

Именования экшенов контроллера

В API контроллера есть 5 видов экшенов и все зависят от типа AJAX запроса:

class Controller_API_Test extends Controller_System_API
{
	// POST Request
	public function post_action_name()

	// GET Request
	public function get_action_name()

	// PUT Request
	public function put_action_name()

	// DELETE Request
	public function delete_action_name()

	// REST Request
	public function rest_get()
	public function rest_post()
	public function rest_put()
	public function rest_delete()
}

Пример вызова (jQuery):

// Controller_API_Test::post_action_name
$.ajax({
  type: "POST",
  url: "/api-test.action_name",
  ....
});

// Controller_API_Test::get_action_name
$.ajax({
  type: "GET",
  url: "/api-test.action_name",
  ....
});

// Controller_API_Test::put_action_name
$.ajax({
  type: "PUT",
  url: "/api-test.action_name",
  ....
});

// Controller_API_Test::delete_action_name
$.ajax({
  type: "DELETE",
  url: "/api-test.action_name",
  ....
});

////////////////////////////////
// REST
////////////////////////////////

// Controller_API_Test::rest_post
$.ajax({
  type: "POST",
  url: "/api-test",
  ....
});

// Controller_API_Test::rest_get
$.ajax({
  type: "GET",
  url: "/api-test",
  ....
});

// Controller_API_Test::rest_put
$.ajax({
  type: "PUT",
  url: "/api-test",
  ....
});

// Controller_API_Test::rest_delete
$.ajax({
  type: "DELETE",
  url: "/api-test",
  ....
});

Параметры контроллера

public $public_actions = array();

Экшены контроллера к которым разрешен публичный доступ без использования ключа (Указываются без типа запроса, например array('action_name')).

protected $_check_token = FALSE;

Проверять ли токен в момент выполения запроса. Токен передается с ключом token (Security::token()). Если токен не валиден, в ответ придет

{code: 110, message: "Error security token"}

public $json = array();

Значения, которые будут возвращены в ответе на запрос клиента. Массив будет кодирован в json фомарт.

Методы контроллера

public function param($key, $default = NULL, $is_required = FALSE)

Получение переданного значения в запросе. $key - ключ параметра $default - значение по умолчанию, если параметр с таким значением не передан $is_required - значение обязательно должно присутствовать в запросе. Если указать параметр в TRUE, то в случае отсутствия в запросе такого значения в ответ придет

{code: 140, message: "Missing param :key"}

public function json_redirect($uri)

Указание страницы редиректа, в ответ вернется

{ ...., redirect: "uri"}

public function message( $message )

Указание текста сообщения, в ответ вернется

{ ...., message: "message"}

public function response($data)

Указание данных ответа.

{ ...., response: data}

---

Использование класса API

Внутри системы написан модуль для работы с API, это фактически обертка над Request и Response.

Запросы могут быть 4 типов:

• Api::get()
• Api::post()
• Api::put() - должен обязательно содержать параметр id
• Api::delete()

Также на всякий случай доступен Api::request()

Пример запроса данных: $request = Api::get('pages.get', array('fields' => 'id,title')); вернет объект API_Response И далее работа происходит с его методами:

$request->body() - вернет json ответ $request->as_array() - данные в виде массива $request->as_object() - в виде объекта $request->status() - статус ответа, если код не 200, то FALSE $request->code() - код ответа $request->error() - текст ошибки

Параметры запроса

В каждом запросе должен присутствовать набор обязательных параметров. Также для каждой функции в ее документации определены дополнительные параметры, нужные только для этой функции.

Порядок следования параметров в запросе значения не имеет, порядок параметров важен только при расчете подписи.

Одинаковые для всех функций параметры перечислены ниже: fields - в параметре передается список полей, которые нужно получить в запросе (через запятую)

Ответ от сервера

Все ответы приходят в формате JSON и содержат один обязательный параметр code, который содержит статус текущего ответа ( link ):

• 200 - Запрос успешно выполнен
• 110 - Отсутствует обязательный параметр
• 120 - Ошибка валидации данных (POST и PUT запрос)
• 130 - Неизвестная ошибка
• 140 - Ошибка токена
• 220 - Отсутсвуют права на доступ к данным
• 404 - Метод API не найден