API

Общие положения

Описание

REST API сервиса Estismail определяет набор функций для осуществления взаимодействия по протоколу HTTP. Все ответы по умолчанию приходят в виде JSON структур. Так же возможно получать ответы в формате XML.

Авторизация

Процесс авторизации происходит с помощью персонального ключа API key, который передается с каждым запросом к API через HTTP — заголовок X-Estis-Auth. Для получения данного ключа перейдите в меню "Мой кабинет" раздел "Мои настройки" на вкладку API и нажмите кнопку «Сгенерировать».

Основной URL

Взаимодействие осуществляется с помощью HTTP запросов с параметрами в кодировке UTF-8 к URL: https://v1.estismail.com/[section]/[resource].
Обязательным является использование HTTPS соединения.

Используемые HTTP — методы:

Основные методы API:

Некоторые ресурсы не обязательно содержат полный набор методов. Если в определённом ресурсе метод не реализован, будет возвращена ошибка 405 Not Allowed. Подробное описание методов смотрите в спецификации конкретного ресурса.

Стандартные опциональные параметры

Методы index и view(только параметр fields) каждого из ресурсов предоставляют набор стандартных параметров для удобной выборки данных, к которым относятся:

limit - используется для задания количества отображаемых элементов. Значение по умолчанию: 10. Диапазон значений: 1 - 100. Если передан limit, выходящий за диапазон допустимых значений, устанавливается значение по умолчанию.

page - номер страницы. Если передан неправильный номер страницы, устанавливается значение по умолчанию = 1.

fields - строка в формате json, содержащая массив полей ["key1","key2", ...], которые будут выбраны для конкретного ресурса.

filter - строка в формате json, содержащая обьект вида {"key1":"value1","key2":"value2", ...}, где keyN - название N-го поля, valueN - значение N-го поля, по которым будут отфильтрованы выбираемые данные. Фильтрация проводится по точному схождению переданных значений с данными в системе.

sort_field - строка, которая содержит поле, по которому будет проводиться сортировка. Значение по умолчанию: id.

sort_direction - предоставляет возможность задать способ сортировки выбираемых данных. Доступные параметры: 1 - по возрастанию, -1 - по убыванию. Значение по умолчанию: по возрастанию.

Допустимые поля и их значения для каждого из параметров смотрите в спецификации конкретного ресурса.

Возможные статусы ответов HTTP — запросов

Пример обращения к API на PHP

$apiKey = 'sdfhdsgfhjsgdbjhvshfkywjhgfksdjfhbkjds';
$resourceUrl = 'https://v1.estismail.com/mailer/lists';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $resourceUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
	'X-Estis-Auth: '.$apiKey
));
$response = curl_exec($ch);
curl_close($ch);