Наверх

Документация ad1 API BETA

 Внимание: API находится на стадии активной разработки. В скором времени он будет дополнен множеством новых методов, однако возможны изменения в существующих методах. О важных изменения мы обязательно уведомим вас, оставайтесь на связи.

Начало работы

В документе описан программный интерфейс сервиса ad1 (далее — «API»). Через API внешние приложения добавляют и редактируют офферы, цели, промоматериалы, получают списки офферов, лидов, а также всевозможную статистику.

Предполагается, что читатель владеет терминологией и понимает принципы работы CPA сетей. Эта информация содержится в справке сервиса.

Варианты использования

API предусматривает различные уровни доступа к объектам системы, эти уровни соответствуют типам аккаунтов. Без авторизации доступен уровень "Гость", используя который можно получить информацию, также доступную без регистрации на сайте: список доступных офферов, их целей, новости и т.д. Уровни "Вебмастер" и "Рекламодатель" соответствуют функционалу аналогичных аккаунтов на сайте.

Доступ

Общедоступная информация, вроде списка офферов, их целей, категорий и т.п. доступна без авторизации.

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

REST

API построено по принципу REST. Для получения доступа к любому ресурсу достаточно сделать обычный HTTP запрос.

В общем случае, url ресурса выглядит так: /api/<resource_name>, всего может быть 5 методов взаимодействия с ресурсом.

Метод Запрос Назначение
list GET /api/resource/

Получить список объектов, согласно заданным параметрам. Используется, в основном, для полной выгрузки информации, также может использоваться для поиска.

Список объектов может быть найден в поле objects ответа.

Чаще всего, метод list не возвращает сразу все найденные объекты, вместо этого, ответ разбивается на несколько частей, другими словами, включается механизм пагинации.

Если для метода list данного ресурса используется пагинация, в ответе сервера, кроме поля objects, появляются еще три поля:

  • total_count Сколько всего найдено объектов, согласно переданным параметрам.
  • per_page Сколько объектов отображается "на странице", то есть возвращается с сервера в ответ на один запрос.
  • page Текущая страница, другими словами, порция объектов.

 

page и per_page являются также и параметрами запроса. per_page по умолчанию равен 100 и это его максимальное значение. Можно выбрать любое значение между 10 и 100. page по умолчанию равно 1, и увеличивается для получения следующей страницы результатов.

Можно высчитывать количество страниц для каждого запроса, деля значение total_count на per_page, но мы рекомендуем просто увеличивать page на один и ожидать пустого поля objects в ответе — это будет означать, что все объекты уже переданы.

view GET /api/resource/id

Получить один объект с заданным ID. Обычно, содержит более полную информацию, чем в списке действия list.

Возвращаемый объект будет находиться в поле object ответа.

update POST /api/resource/id

Редактировать объект с переданным ID. В теле запроса необходимо передать поля объекта, которые следует изменить, и их новые значения.

В случае успеха, поле ответа updated будет содержать ID отредактированного объекта.

create POST /api/resource/

Создать новый объект. В теле запроса необходимо передать поля нового объекта, и их значения.

В случае успеха, поле ответа created будет содержать ID созданного объекта.

Также, код статуса ответа на этот запрос, в случае успеха, будет 201, а не 200, как у всех остальных методов.

delete

DELETE /api/resource/id или

POST /api/resource/del/id

Удалить объект. Для совместимости с некоторыми видами proxy серверов поддерживатеся альтернативный url с методом POST.

В случае успеха, поле ответа deleted будет содержать ID удаленного объекта.

Очевидно, что не каждый ресурс поддерживает все 5 методов взаимодействия. Полный список доступных методов для каждого типа аккаунта можно увидеть в меню "Ресурсы и методы" слева.

Параметры запросов

Используется базовый способ передачи данных по HTTP. В случае GET запросов — параметры передаются в виде строки параметров url, в случае POST,PUT,DELETE — в теле запроса.

Дополнительная сериализация запроса не требуется, однако, обратите внимание, в некоторых случаях необходимо использовать кодирование url.

Ответы сервера и ошибки

Формат данных ответа — всегда JSON. В таблице выше можно увидеть, какие поля следует ожидать в ответе в случае успешного запроса. В случае ошибки в ответе сожержится только поле error.

Общее правило такое: если в ответе нет поля error, значит запрос выполнен успешно, и в ответе нужно искать поле, соответствующее запросу (см. таблицу методов).

В поле error сожержится наиболее подробное описание ошибки. В этом поле может передаваться как строка, так и более сложная структура данных, например:

GET /api/geo?api_key=wrongkey

{ "error": "Unauthorized" }

GET /api/goal/?offer_id=-123

{ "error": { "offer_id": ["Offers not found"] } }

Кроме описания ошибки в поле error, общая информация об ответе (в том числе об ошибке) передается в коде статуса HTTP. Список используемых кодов:

Код Расшифровка Используется для
200 OK Запрос выполнен успешно
201 Created Объект создан
400 Bad Request Ошибка в параметрах запроса
401 Unauthorized Ошибка авторизации (ключ API неверен)
403 Forbidden У вас нет прав на выполнение этого метода над этим ресурсом
404 Not found Объект не найден
405 Method not allowed Этот ресурс не поддерживает требуемый метод
500 Internal server error Ошибка с нашей стороны
501 Not implemented Метод пока не реализован, но скоро будет доступен