Формат JSON

Во многих языках программирования существуют модули и библиотеки для работы с JSON. Ниже перечислены рекомендуемые модули и библиотеки для популярных языков.

Perl: модуль JSON;
PHP: встроенная поддержка JSON начиная с версии 5.2.0;
Python: модуль json.

JSON-запросы

Адрес для запросов указан в документации каждого сервиса.

Запрос всегда содержит ключ method с именем вызываемого метода и в большинстве случаев ключ params (см. пример ниже). Некоторые методы не имеют входных параметров, и для них ключ params не требуется.

Пример запроса

Вызов метода Ads.add для добавления объявлений рекламодателю agrom, выполняемый от имени рекламного агентства.

POST /json/v5/ads/ HTTP/1.1
Host: api.direct.yandex.com
Authorization: Bearer 0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f
Accept-Language: ru
Client-Login: agrom
Content-Type: application/json; charset=utf-8

{
  "method": "add",
  "params": {
    "Ads": [{ 
      "AdGroupId": 1234567,
      "TextAd": {
        "Text": "Слоны всех пород. Сертифицированный питoмник",
        "Title": "Купи слона!",
        "Href": "http://exotic-farm.com/elefants",
        "Mobile": "NO"
      }
    },
    { 
      "AdGroupId": 1234567,
      "TextAd": {
        "Text": "Носороги с доставкой. Весенняя распродажа",
        "Title": "Купи носорога!",
        "Mobile": "NO"
      }
    }]
  }
}

Пример ответа

HTTP/1.1 200 OK
Connection:close
Content-Type:application/json; charset=utf-8
Date:Fri, 28 Nov 2014 17:07:02 GMT
RequestId:1010101010101010101
Units:10/20828/64000
Units-Used-Login:agrom
Server:nginx
Transfer-Encoding:chunked

{
  "result": {
    "AddResults": [{
      "Id": 7654321
    }, /* Объявление успешно создано, возвращен его идентификатор */
    {
      "Errors": [{
        "Code": 6000,
        "Message": "Неконсистентное состояние объекта",
        "Details": "В объявлении должна быть указана или визитка или основная ссылка"
      }] /* Ошибка создания объявления */
    }]
  }
}

Пример ошибки

Если выполнение запроса невозможно, возвращается сообщение об ошибке.

HTTP/1.1 200 OK
Connection:close
Content-Type:application/json; charset=utf-8
Date:Fri, 28 Nov 2014 17:07:02 GMT
RequestId:1010101010101010101
Units:10/20828/64000
Units-Used-Login:agrom
Server:nginx
Transfer-Encoding:chunked

{
  "error" : {
    "request_id": "1010101010101010101",
    "error_code": 8000,
    "error_string": "Некорректный запрос",
    "error_detail": "В TextAd отсутствует обязательное поле Text"
  }
}

Подробнее об ошибках см. в разделе Обработка ошибок.