Главная API для разработчиков

API для разработчиков

API (Application Programming Interface) — это интерфейс программирования. Набор готовых функций и программного кода, предоставляемых приложением. Используется программистами для интеграции сервиса со сторонними приложениями.

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

Описание

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 — методы:

Метод	Описание
get	Получение ресурса.
post	Создание ресурса.
put	Обновление ресурса.
delete	Удаление ресурса.

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

Имя метода	Описание
index	Получение полного списка элементов ресурса.
view	Получение одного элемента списка ресурсов.
add	Добавление нового элемента в ресурс.
edit	Редактирование элемента ресурса.
delete	Удаление элемента ресурса.

Некоторые ресурсы не обязательно содержат полный набор методов. Если в определённом ресурсе метод не реализован, будет возвращена ошибка 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 — запросов

Код ответа	Описание
Успешные
200 OK	Успешный запрос. При успешном выполнении методов index и view.
201 Created	В результате успешного выполнения запроса был создан новый ресурс. Используется в методе add при успешном запросе.
204 No Content	Сервер успешно обработал запрос, но в ответе были переданы только заголовки без тела сообщения. Используется в методах edit и delete при успешном запросе.
Ошибки клиента
400 Bad Request	Сервер обнаружил в запросе клиента синтаксическую ошибку. Неправильно переданы параметры или переданных параметров недостаточно для успешной обработки.
401Unauthorized	Для доступа к запрашиваемому ресурсу требуется аутентификация. Отсутствует или неправильный HTTP-заголовок X-Estis-Auth.
404 Not Found	Сервер понял запрос, но не нашёл соответствующего ресурса по указанному URI.
405 Not Allowed	Указанный клиентом метод нельзя применить к текущему ресурсу.

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

Пример получения списка групп подписчиков, где $apiKey - Ваш API key.

$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);