Структура запроса к API

  1. Структура запроса
  2. 1. Обращение к хосту API с указанием версии
  3. 2. Авторизация
  4. 3. Навигационный блок
  5. 4. Параметры
  6. Формат передачи значений Дата и время
  7. Кодировка входных параметров

Структура запроса

Запрос к API состоит из блоков, передаваемых в URL:

  1. обращение к хосту API с указанием версии;
  2. авторизация;
  3. навигационный блок;
  4. параметры.

В качестве разделителя параметров используется символ & (амперсанд).

Параметр и значение разделяются символом = (равно).

Внимание. API ADFOX является регистрозависимым — все имена объектов нужно передавать с применением заглавных и строчных букв, как указано в документе.

1. Обращение к хосту API с указанием версии

Хост для всех запросов к API:

https://api.adfox.ru/vX/API.php

где X — номер версии.

Например, запрос к API версии 1 будет такой:

https://api.adfox.ru/v1/API.php

2. Авторизация

В каждом вызове API необходимо передавать:

  1. loginAccount — логин пользователя в системе ADFOX.
  2. loginPassword — значение хеш-функции sha256 от пароля пользователя.

Требования к паролю: должен содержать буквы (прописные и строчные), цифры и другие символы. Длина пароля: не менее 8 символов. Нельзя использовать ранее сгенерированный пароль.

Пример запроса, где логин пользователя — test, sha256 от пароля — h34ghk3...:

https://api.adfox.ru/v1/API.php?loginAccount=test&loginPassword=h34ghk3...

В случае неудачной авторизации API вернет XML-ответ с ошибкой « Authorization failed ».

3. Навигационный блок

Один запрос к API позволяет выполнить одно действие.

В запросе необходимо передать информацию о том, в каком контексте какое действие необходимо произвести с объектом.

За эту информацию отвечает навигационный блок с параметрами:

  1. object — контекст, в котором производится действие.
  2. action — действие, производимое над объектом.

    Для каждого контекста определен набор возможных действий. Примеры действий:

    • add — добавление объекта (доступно только в контексте account);
    • list — получение списка;
    • modify — редактирование объекта;
    • update — изменение параметров объекта;
    • delete — удаление объекта (доступно только в контексте account).
  3. actionObject — имя объекта, над которым производится действие.

    В некоторых методах actionObject может отсутствовать (например, в методах: account-changePassword, account-auth, advertiser-modify, assistant-modify).

4. Параметры

Последний блок в запросе API составляют параметры вызываемого метода:

  1. обязательные — например:

  2. необязательные — параметры указываются в квадратных скобках, например:

    Если параметр не будет передан в запросе, то API будет использовать для этого параметра значение по умолчанию. Значения по умолчанию смотрите на странице у конкретного actionObject.

Поиск нужного метода в документации

Описания методов API в документе сгруппированы по контекстам, в которых они производятся, а внутри контекста — по типам действий. Поэтому чтобы найти нужный метод в документе, нужно построить цепочку контекст—действие—объект, аналогичную навигационному блоку запроса. Ниже приведено несколько примеров.

Варианты передачи параметров в запросе к API

Существует два варианта передачи блока навигации и блока с параметрами запроса:

Формат передачи значений «Дата и время»

Формат передачи даты: YYYY-MM-DD.

Формат передачи времени: HH:mm.

Формат передачи времени с секундами: HH:mm:ss.

Формат передачи даты и времени: YYYY-MM-DD HH:mm, где

  • YYYY — год;
  • MM — месяц;
  • DD — день;
  • HH — час;
  • mm — минута.
Примечание. Значения даты и времени записываются через пробел.

Например:

dateStart=2015-04-25 11:00&action=…
Примечание. Для параметров дата/время — время является необязательным значением. По умолчанию выставляется в 00:00.

Кодировка входных параметров

Если в запросе к API передаются кириллические символы, то необходимо указывать кодировку входных параметров в параметре encoding.

Возможные значения:

  • UTF-8 (рекомендуется);
  • CP-1251.

Например:

encoding=UTF-8