Справочная информация

Синтаксис запроса

Чтобы обратиться к любому методу API (за исключением метода execute, о нём ниже), вам необходимо выполнить POST или GET запрос такого вида:

<a href="<a href=" http:="" you_ointeres.site.ru="" api="" method="" method_name?parameters&api_key="API_KEY" "=""></a><a href="http://you_ointeres.site.ru/api/method/METHOD_NAME...</a>"><a">http://you_ointeres.site.ru/api/method/METHOD_NAME...</a"></a> href="<a href="http://you_ointeres.site.ru/api/method/METHOD_NAME...">http://you_ointeres.site.ru/api/method/METHOD_NAME...</a>"><a href="http://you_ointeres.site.ru/api/method/METHOD_NAME...">http://you_ointeres.site.ru/api/method/METHOD_NAME...</a>

Он состоит из нескольких частей:

• METHOD_NAME (обязательно) — название метода этой странице.
• PARAMETERS (опционально) — входные параметры соответствующего метода API, последовательность пар name=value, разделенных амперсандом. Список параметров указан на странице с описанием метода. Значения параметров должны быть в кодировке UTF-8.
• API_KEY — ключ доступа.

Параметры могут передаваться как методом GET, так и POST. Если вы будете передавать большие данные (больше 2 килобайт), следует использовать POST.

Формат METHOD_NAME состоит из названия контроллера, названия экшена и параметров экшена. Контроллер, экшен и параметры разделены символом ».» (точка). Например, мы имеем METHOD_NAME с названием

content.get_datasets.articles

• content — название контроллера (компонента);
• get_datasets — действие (экшен) контроллера;
• articles — первый параметр этого действия.

Например, вызовем метод

content.get_datasets.articles

<a href="<a href=" http:="" you_ointeres.site.ru="" api="" method="" content.get_datasets.articles?api_key="API_KEY&show_all=1" "=""></a><a href="http://you_ointeres.site.ru/api/method/content.get...</a>"><a">http://you_ointeres.site.ru/api/method/content.get...</a"></a> href="<a href="http://you_ointeres.site.ru/api/method/content.get...">http://you_ointeres.site.ru/api/method/content.get...</a>"><a href="http://you_ointeres.site.ru/api/method/content.get...">http://you_ointeres.site.ru/api/method/content.get...</a>

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

{      "response":{         "count":5,       "items":{            "all":{               "id":"1",             "ctype_id":"5",             "name":"all",             "title":"Все",             "description":null,             "ordering":"1",             "is_visible":"1",             "filters":[  ],             "sorting":[  ],             "index":"date_pub",             "groups_view":[  ],             "groups_hide":[  ],             "seo_keys":null,             "seo_desc":null          },          "reviews":{  },          "translations":{  },          "featured":{  },          "rating":{  }       }    } }

Обратите внимание, ответы возвращаются только в формате JSON.

API также поддерживает универсальный метод, который позволяет запускать последовательность других методов, сохраняя промежуточные результаты и возвращая их все в одном ответе. Внимание! Запрос будет иметь другой базовый вид:

<a href="<a href=" http:="" you_ointeres.site.ru="" api="" execute?parameters&api_key="API_KEY" "=""></a><a href="http://you_ointeres.site.ru/api/execute?PARAMETERS...</a>"><a">http://you_ointeres.site.ru/api/execute?PARAMETERS...</a"></a> href="<a href="http://you_ointeres.site.ru/api/execute?PARAMETERS...">http://you_ointeres.site.ru/api/execute?PARAMETERS...</a>"><a href="http://you_ointeres.site.ru/api/execute?PARAMETERS...">http://you_ointeres.site.ru/api/execute?PARAMETERS...</a>

Разбивка на страницы

В ответах, где отдаётся список чего-либо с возможностью разбивки на страницы, присутствует объект paging, содержащий ячейки:

• has_next (true или false) — флаг наличия следующей страницы;
• page — номер текущей страницы;
• per_page — количество элементов на одну страницу.

Обработка ошибок

На все запросы к методам

you_ointeres.site.ru/api/method/

you_ointeres.site.ru/api/execute/

{      "error":{         "error_code":101,       "error_msg":"Неверный ключ доступа",       "request_params":[  ]    } }

Коды ошибок (error_code) совпадают в своем большинстве с кодами ошибок Вконтакте. В ячейке error_msg указывается текстовое представление ошибки на выбранном языке. В некоторых сообщениях об ошибках присутствует непустое поле request_params с массивом названий параметров и ошибками их валидации.

Разработчикам методов

Разработка методов экшена или хука, на ваш выбор.

Метод как экшен

Внешние экшены контроллера. Например, мы хотим создать экшен для метода API

youcontroller.list_items

api_youcontroller_list_items

Файл экшена будет называться соответственно:

api_youcontroller_list_items.php

И располагаться по пути

/system/controllers/youcontroller/actions/api_youcontroller_list_items.php

Далее создаётся код экшена стандартным способом, но с некоторыми обязательными свойствами:

class actionYoucontrollerApiYoucontrollerListItems extends cmsAction {       /**      * Блокировка прямого вызова экшена      * обязательное свойство      * @var boolean      */     public $lock_explicit_call = true;     /**      * Результат запроса      * обязательное свойство      * @var array      */     public $result;     /**      * Массив названий ячеек      * которые нужно удалить из результирующего массива      * необязательное свойство      * @var array      */     public $unset_fields;     /**      * Флаг, обязующий проверять параметр sig запроса      * sig привязан к домену сайта и к ip адресу посетителя      * @var boolean      */     public $check_sig = false;     /**      * Флаг, обязующий проверять авторизацию пользователя      * @var boolean      */     public $auth_required = false;     /**      * Флаг, обязующий проверять авторизацию пользователя      * И принадлежность пользователя к административному доступу      * @var boolean      */     public $admin_required = false;     /**      * Возможные параметры запроса      * с правилами валидации      * Если запрос имеет параметры, необходимо описать их здесь      * Правила валидации параметров задаются по аналогии с полями форм      * @var array      */     public $request_params = <a href="<a href=" http:="" <a="" ""="">www.php.net=""</a> array"="">array()"><a href="<a href=" <a="">array</a>()"><a href="<a href=" http:="" www.php.net="" array"="">array</a>()"><a href="<a href=" http:="" www.php.net="" array"="">array</a>()"><a href="<a href=" http:="" www.php.net="" array"="">array</a>()">http://www.php.net/array">array</a>()">http://www.php.net/array">array</a>()">http://www.php.net/array">array()"><a href="http://www.php.net/array">array()">http://www.php.net/array">array()</a>"><a href="http://www.php.net/array">array()">http://www.php.net/array">array()</a>"><a href="http://www.php.net/array">array()">http://www.php.net/array">array()</a>;     /**      * Необязательный метод проверки запроса      * В нём выполняются некий действия по валидации      * возвращает либо false в случае успешной проверки      * либо массив данных ошибки       */     public function validateApiRequest() { return false; }     /**      * Основной метод работы экшена      * Его задача заполнить свойство $this->result      */     public function run(){         $this->result = array('items' => array());     }   }
	

Метод как хук

Отличие это варианта лишь в расположении файла и именовании класса. Учитывая пример выше, в этом случае файл хука должен быть расположен по пути:

/system/controllers/youcontroller/hooks/api_youcontroller_list_items.php

А класс называться:

class onYoucontrollerApiYoucontrollerListItems extends cmsAction {}