help - API-methods
Описание методов API
Все методы API сгруппированные по компонентам.
Контент
Название | Описание |
---|---|
content.get_ctypes | Возвращает все типы контента. |
content.get_datasets.CTYPE | Возвращает наборы для заданного типа контента. |
content.get_categories.CTYPE | Возвращает категории для заданного типа контента. |
content.get_fields.CTYPE | Возвращает поля записей для заданного типа контента. |
content.get_props.CTYPE | Возвращает свойства категорий для заданного типа контента. |
content.get_props_values.CTYPE | Возвращает значения свойств записи для заданного типа контента. |
content.get_folders.CTYPE | Возвращает папки записей для заданного типа контента. |
content.get.CTYPE | Возвращает записи для заданного типа контента. |
content.get_item.CTYPE | Возвращает одну запись для заданного типа контента. |
content.update_item.CTYPE | Редактирует одну запись для заданного типа контента. |
content.add_item.CTYPE | Добавляет запись в заданный тип контента. |
Примечание. CTYPE - название типа контента, например news, board, articles и т.д.
Авторизация и регистрация
Название | Описание |
---|---|
auth.signup_fields | Получает имена полей, обязательных для регистрации. |
auth.signup | Регистрирует нового пользователя. |
auth.confirm | Завершает регистрацию нового пользователя, начатую методом auth.signup. |
auth.restore | Отправка запроса на восстановление пароля пользователя. |
auth.login | Авторизация пользователя стандартным способом (используются cookie). |
auth.logout | Разавторизация пользователя. |
Пользователи
Название | Описание |
---|---|
users.get | Возвращает информацию о пользователях. |
users.get_sig | Возвращает SIG и csrf_token. |
users.add | Добавляет пользователя. |
users.get_groups | Возвращает все группы пользователей. |
users.add_to_groups | Добавляет пользователя в группы. |
users.remove_from_groups | Убирает пользователя из групп. |
Стена
Название | Описание |
---|---|
wall.get | Возвращает список записей со стены пользователя или группы. |
Комментарии
Название | Описание |
---|---|
comments.get | Получает комментарии. |
Личные сообщения
Название | Описание |
---|---|
messages.send | Отправляет сообщение. |
messages.delete_contact | Удаляет контакт. |
messages.delete_mesages | Удаляет сообщения. |
messages.delete_notice | Удаляет уведомления. |
messages.forgive | Прекращает игнорирование контакта. |
messages.ignore | Включает игнорирование контакта. |
messages.get | Возвращает список сообщений. |
messages.get_notices | Возвращает список уведомлений. |
messages.readed | Помечает сообщения как прочитанные. |
messages.restore_mesage | Восстанавливает сообщение. |
Местоположение
Название | Описание |
---|---|
geo.get | Возвращает список стран/регионов/городов. |
geo.get_current_country | Возвращает данные по текущей стране пользователя, если она была определена по его ip адресу. |
Загрузка изображений
Название | Описание |
---|---|
images.get_presets | Возвращает список всех доступных пресетов. |
images.upload | Загружает изображение. |
Общие методы
Название | Описание |
---|---|
execute | Универсальный метод, который позволяет запускать последовательность других методов, сохраняя промежуточные результаты и возвращая их все в одном ответе. |
JSON API
Описание
Компонент реализует легкое API между сайтом и сторонним сервисом, например, мобильным приложением. Компонент позволяет вести логи ошибок и успешных запросов, выводя их в диаграмме на главной страницы админ-панели. В основном, синтаксис запросов и формат ответов схож с официальными API. Это сделано специально, для более легкого понимания интеграторами. Ответы API возвращаются только в JSON формате.
Настройки
Логировать запросы с ошибками
Включает логирование ошибочных запросов.
Логировать успешные запросы
Включает логирование успешных запросов. Внимание! Фиксируется каждый запрос к API.
Для каждого тип запроса фиксируется:
-
id ключа;
-
Название метода API;
-
Код ошибки, при наличии таковой;
-
Дата запроса;
-
Время, потраченное на обработку запроса.
Авторизация
Все запросы к API подписываются ключом доступа, который создаётся в админ-панели компонента. Для запросов чтения этого достаточно. Ключ API можете передаваться как в POST/GET параметре, так и в заголовке запроса с именем api_key
. Длина ключа может быть не более 32 символов. При создании ключ генерируется автоматически, однако его можно вручную изменить. Каждый ключ можно ограничить по ip адресу, временно выключить.
Для каждого ключа можно задать ограничения по ip адресам и по методам, которые будут доступны для данного ключа.
Другие методы авторизации и подписывания запросов, а также механизм авторизации пользователей - в разработке.
Синтаксис запроса
Чтобы обратиться к любому методу API (за исключением метода execute, о нём ниже), вам необходимо выполнить POST или GET запрос такого вида:
http://this.site/api/method/METHOD_NAME?PARAMETERS&api_key=API_KEY
Он состоит из нескольких частей:
-
METHOD_NAME (обязательно) — название метода API, к которому Вы хотите обратиться. Полный список методов доступен на этой странице.
-
PARAMETERS (опционально) — входные параметры соответствующего метода API, последовательность пар name=value, разделенных амперсандом. Список параметров указан на странице с описанием метода. Значения параметров должны быть в кодировке UTF-8.
-
API_KEY — ключ доступа.
Параметры могут передаваться как методом GET, так и POST. Если вы будете передавать большие данные (больше 2 килобайт), следует использовать POST.
Формат METHOD_NAME состоит из названия контроллера, названия экшена и параметров экшена, что в целом схоже с основным роутингом InstantCMS. Контроллер, экшен и параметры разделены символом ».» (точка). Например, мы имеем METHOD_NAME с названием content.get_datasets.articles
:
-
content - название контроллера (компонента);
-
get_datasets - действие (экшен) контроллера;
-
articles - первый параметр этого действия.
Например, вызовем метод content.get_datasets.articles
, чтобы получить список всех наборов типа контента с названием articles и укажем в параметре, что нам нужно вернуть все наборы, включая скрытые:
http://this.site/api/method/content.get_datasets.articles?api_key=API_KEY&show_all=1
Вы получите ответ в формате 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.
Компонент также поддерживает универсальный метод, который позволяет запускать последовательность других методов, сохраняя промежуточные результаты и возвращая их все в одном ответе. Внимание! Запрос будет иметь другой базовый вид:
http://this.site/api/execute?PARAMETERS&api_key=API_KEY
Разбивка на страницы
В ответах, где отдаётся список чего-либо с возможностью разбивки на страницы, присутствует объект paging, содержащий ячейки:
-
has_next (true или false) - флаг наличия следующей страницы;
-
page - номер текущей страницы;
-
per_page - количество элементов на одну страницу.
Определение IP адреса посетителя
В случае, если запросы к api выполняются из одного места, например из скрипта PHP на сервере, но при этом необходимо, чтобы ip адрес посетителей учитывался в API, вы можете передавать ip адрес в параметре запроса с названием ip, например:
http://this.site/api/method/METHOD_NAME?PARAMETERS&api_key=API_KEY&ip=8.8.8.8
Обработка ошибок
На все запросы к методам
this.site/api/method/
и/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
Разработчикам методов
Разработка методов API для ваших компонентов достаточно проста. Весь процесс разработки метода сводится к созданию специального экшена или хука, на ваш выбор.
Метод как экшен
Компонент InstantCMS API поддерживает только внешние экшены контроллера. Например, мы хотим создать экшен для метода 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 = array(); /** * Необязательный метод проверки запроса * В нём выполняются некий действия по валидации * возвращает либо 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 {}