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 - количество элементов на одну страницу.

В случае, если запросы к 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 с массивом названий параметров и ошибками их валидации.

Просмотреть весь список методов 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 {}