помощь - API-методы

Описание методов 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 {}



авторизируйтесь

Авторизация