Справочная информация
Синтаксис запроса
Чтобы обратиться к любому методу 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, чтобы получить список всех наборов типа контента с названием 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/, включая запросы с ошибками возвращают HTTP CODE 200. Ошибки генерируются в JSON ответе специальным образом:
{ "error":{ "error_code":101, "error_msg":"Неверный ключ доступа", "request_params":[ ] } }
Коды ошибок (error_code) совпадают в своем большинстве с кодами ошибок Вконтакте. В ячейке error_msg указывается текстовое представление ошибки на выбранном языке. В некоторых сообщениях об ошибках присутствует непустое поле request_params с массивом названий параметров и ошибками их валидации.
Код | Описание |
---|---|
1 | Произошла неизвестная ошибка |
2 | Ключ доступа выключен |
3 | Передан неизвестный метод |
5 | Авторизация пользователя не удалась |
7 | Нет прав для выполнения этого действия |
71 | Требуется авторизация пользователя |
710 | Требуется административный доступ |
8 | Неверный запрос |
15 | Доступ запрещён |
115 | Параметр sig не передан или является некорректным |
23 | Метод был выключен |
24 | Метод вам недоступен |
100 | Один из необходимых параметров был не передан или неверен |
101 | Неверный ключ доступа |
115 | Параметр sig не передан или является некорректным |
777 | ip адрес посетителя передан некорректный |
Разработчикам методов
Разработка методов экшена или хука, на ваш выбор.
Метод как экшен
Внешние экшены контроллера. Например, мы хотим создать экшен для метода API
youcontroller.list_items
, который будет отдавать нам список неких записей. Механизм формирования названия экшена такой:api_youcontroller_list_items
Файл экшена будет называться соответственно:
api_youcontroller_list_items.php
И располагаться по пути
/system/controllers/youcontroller/actions/api_youcontroller_list_items.php.
Далее создаётся код экшена стандартным способом, но с некоторыми обязательными свойствами:
api_youcontroller_list_items.phpclass 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 {}