Документация Каталог Услуги Контакты
Главная Документация API

JSON API

Взаимодействие с InstantCMS через программный интерфейс

JSON
API Key
GET / POST

Обзор API

Компонент для интеграции с внешними сервисами

Компонент API реализует программный интерфейс для взаимодействия между сайтом на InstantCMS и сторонними сервисами: мобильными приложениями, внешними системами и другими платформами. Все ответы возвращаются исключительно в формате JSON.

JSON-формат

Все ответы API возвращаются в формате JSON для удобной обработки

Авторизация по ключу

Безопасный доступ через API-ключи с ограничениями по IP и методам

Логирование

Система логирует запросы, отслеживает ошибки и выводит статистику

Совместимость

Синтаксис API совместим с API ВКонтакте, что упрощает интеграцию для разработчиков, знакомых с этой платформой.

Аутентификация

Доступ к API через ключи авторизации

Для доступа к API используется ключ авторизации длиной до 32 символов. Ключ можно передать двумя способами:

Параметр запроса
?api_key=ВАШ_КЛЮЧ

Передача через GET или POST параметр api_key

HTTP-заголовок
api_key: ВАШ_КЛЮЧ

Передача через заголовок запроса api_key

Ограничения ключа

По IP-адресам

Ограничение списка IP-адресов, с которых разрешены запросы

По методам

Ограничение списка доступных для ключа методов API

Деактивация

Возможность временного отключения ключа без удаления

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

Формат обращения к методам API

Базовый формат

URL запроса
http://site.ru/api/method/METHOD_NAME?PARAMETERS&api_key=API_KEY

Структура METHOD_NAME

Имя метода состоит из трёх частей, разделённых точками:

Контроллер .
Действие .
Параметр
Пример
content.get_datasets.articles
GET vs POST

Поддерживаются методы GET и POST. Для передачи данных объёмом более 2 КБ используйте POST-запросы.

Определение IP посетителя

При обращении к API со стороннего сервера можно передать IP-адрес конечного пользователя через параметр ip. Это позволяет системе корректно идентифицировать посетителя.

Метод Execute

Последовательное выполнение нескольких методов

Метод execute позволяет запускать последовательность нескольких методов API в одном запросе, сохраняя промежуточные результаты между вызовами.

URL запроса Execute
http://site.ru/api/execute?PARAMETERS&api_key=API_KEY
Оптимизация

Используйте execute для уменьшения количества HTTP-запросов, объединяя несколько вызовов API в один.

Обработка ошибок

Формат ответов и коды ошибок API

Все запросы к API возвращают HTTP-статус 200. Информация об ошибках передаётся в теле JSON-ответа:

Формат ответа с ошибкой JSON 
{
  "error": {
    "error_code": 101,
    "error_msg": "Текст ошибки",
    "request_params": []
  }
}

Основные коды ошибок

Код Описание Причина
2 Ключ выключен API-ключ деактивирован администратором
3 Неизвестный метод Запрошенный метод не существует в системе
7 Недостаточно прав Ключ не имеет доступа к данному методу
101 Неверный ключ Переданный ключ не найден в системе
710 Требуется админ-доступ Метод доступен только с правами администратора

Разработка методов

Создание собственных методов API

Существует два способа реализации собственных методов API: через экшен контроллера или через хук.

Способ 1: Экшен контроллера

Расположение файла
/system/controllers/yourcontroller/actions/api_yourcontroller_list_items.php

Обязательные свойства класса

$lock_explicit_call = true

Блокирует прямой вызов экшена, разрешая доступ только через API

$result

Массив с результатом выполнения метода, возвращаемый клиенту

$request_params

Описание принимаемых параметров и правила их валидации

Опциональные свойства

$unset_fields

Список полей, исключаемых из ответа

$check_sig

Включает проверку цифровой подписи запроса

$auth_required

Метод требует авторизации пользователя

$admin_required

Метод доступен только администраторам

Методы класса

validateApiRequest()

Дополнительная валидация входящего запроса перед выполнением

run()

Основная логика метода, заполняет свойство $result

Способ 2: Хук

Альтернативный способ — создать хук-класс с определённым именем:

Имя класса хука
onYourcontrollerApiYourcontrollerListItems
Расположение
/system/hooks/

Настройка логирования

Конфигурация записи запросов в панели администратора

Логировать ошибочные запросы

Запись всех запросов, завершившихся ошибкой, для отладки и мониторинга

Логировать успешные запросы

Запись всех успешных запросов для полного аудита и аналитики

Данные лога

Для каждого запроса фиксируются: идентификатор ключа, название метода, код ошибки, дата и время обработки запроса.

Вернуться к документации