Developers
Интерфейсы API
REST

REST интерфейс

Вызов ресурса

Ссылка на ресурс состоит из нескольких частей. Например, /api/rest/webmaster/xml/offers/{type}/{start}/{limit}/{sort}/{sort_type}/{q}/{geo}/{platforms}/{categories}/{traffic_types}?remote_auth=00000000000000000000000000000000

Здесь:

  • /api/rest/webmaster/ - ссылка на библиотеку ресурсов вебмастера
  • /xml/ - формат запрашиваемых данных. Поддерживаемые форматы - xml, json и csv
  • /offers/ - имя ресурса. Все ресурсы описаны в документации
  • далее идут входные параметры
  • remote_auth - обязательный ключ пользователя. Может быть получен через OAuth-авторизацию, либо в личном кабинете вебмастера
Входные параметры

Для GET вызовов доступно несколько способов передачи параметров:

  • В URL - /api/rest/webmaster/xml/offers/{type}/{start}/{limit}/{sort}/{sort_type}/{q}/{geo}/{platforms}/{categories}/{traffic_types}
  • В GET-параметрах - /api/rest/webmaster/xml/offers?type=web&start=0&limit=15
  • Смешанный вариант - /api/rest/webmaster/xml/offers/{type}/{start}?limit=15&sort=cpl&sort_type=desc

Множественные значения одного параметра передаются через запятую. Например, geo=186,150,37.

Внимание! Значения GET-параметров перекрывают значения этих же параметров в URL.

Для PUT и POST запросов следует передавать параметры в теле HTTP-пакета в том же порядке, в котором они описаны в XSD-схеме. Формат представления параметров должен соответствовать типу запрашиваемых данных - XML или JSON

Примеры одного и того же PUT-запроса в XML и JSON форматах:
  • <setUserLanguageRequestData>
    • <lang>ru</lang>
  • </setUserLanguageRequestData>
  • {
    • "lang": "ru"
  • }
Формат ответов

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

  • status - статус запроса
  •  
  • Возможные варианты:
    • 200 - запрос проведен успешно
    • 204 - нет содержимого. Была запущена длительная операция, код которой представлен в поле request_id. Результат операции может быть получен спустя некоторое время по идентификатору request_id
    • 400 - входящие параметры неверны
    • 403 - apiKey некорректен, либо недостаточно прав доступа
    • 404 - запрошенные данные не найдены
    • 500 - внутренняя ошибка
    •  
    • Данный статус код можно продублировать в Код состояния HTTP
  •  
  • error - текст ошибки
    • При успешном запросе значение будет пустым.
  •  
  • request_id - идентификатор операции. Если status = 204, то поле request_id должно содержать число больше 0
  • data - массив с возвращаемыми данными для вызванного метода. При неуспешном запросе будет пустым
Пример:
  • {
    • "status": 204,
    • "error": "",
    • "request_id": 200132
    • "data": [ ],
  • }

Содержание блока data описано в WSDL/XSD.