API (application programming interface) реализует передачу данных между сайтом ointeres.ru и сторонним сервисом, например, Вашим сайтом или мобильным приложением.

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

  • API

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

Чтобы обратиться к любому методу 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.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 {}