API¶

Параметры¶

Некоторые параметры запросов, такие как идентификатор домена, идентификатор пользователя, передаются как часть адреса:

https://biz.mail.ru/api/v1/domain/{domain_id}/users/{user_id}

Остальные параметры передаются в зависимости от типа запроса либо в теле запроса, либо в строке запроса. Для GET-запросов параметры методов передаются в строке запроса.

curl "https://biz.mail.ru/api/v1/test?access_token=5c918ed51f38749782b8b2c3ad41a265e560661137363830&parameter1=value1&parameter2=value2"

GET /api/v1/test?access_token=5c918ed51f38749782b8b2c3ad41a265e560661137363830&parameter1=value1&parameter2=value2
Host: biz.mail.ru

Для остальных типов запросов параметры методов передаются в теле запроса. Содержимое тела запроса в этом случае определяется типом указанным в заголовке Content-Type запроса:

• application/x-www-form-urlencoded

curl -X POST  "https://biz.mail.ru/api/v1/test?access_token=5c918ed51f38749782b8b2c3ad41a265e560661137363830" -d "parameter1=value1&parameter2=value2"

POST /api/v1/test?access_token=5c918ed51f38749782b8b2c3ad41a265e560661137363830
Host: biz.mail.ru
Content-Type: application/x-www-form-urlencoded

parameter1=value1&parameter2=value2

• application/json

curl -X POST  'https://biz.mail.ru/api/v1/test?access_token=5c918ed51f38749782b8b2c3ad41a265e560661137363830' -d '{"parameter1": "value1", "parameter2": "value2"}' -H 'Content-Type: application/json'

POST /api/v1/test?access_token=5c918ed51f38749782b8b2c3ad41a265e560661137363830
Host: biz.mail.ru
Content-Type: application/x-www-form-urlencoded

{"parameter1": "value1", "parameter2": "value2"}

• multipart/form-data

curl -X POST  "https://biz.mail.ru/api/v1/test?access_token=5c918ed51f38749782b8b2c3ad41a265e560661137363830" -F "parameter1=value1" -F "parameter2=value2"

POST /api/v1/test?access_token=5c918ed51f38749782b8b2c3ad41a265e560661137363830'
Host: biz.mail.ru
Content-Type: multipart/form-data; boundary=------------------------------7b1bfd973086

------------------------------7b1bfd973086
Content-Disposition: form-data; name="parameter1"

value1
------------------------------7b1bfd973086
Content-Disposition: form-data; name="parameter2"

value2
------------------------------7b1bfd973086--

Постраничная навигация¶

Результаты некоторых запросов, возвращающих список однотипных элементов, например, список пользователей на домене, выдаются постранично. Атрибут offset показывает смещение выдаваемых элементов в результирующем списке, а атрибут limit - количество выдаваемых элементов на странице, причем limit по умолчанию равен 25 и может принимать максимальное значение, равное 100.

GET /domains/1/users?limit=25&offset=25

В ответе на запрос возвращается словарь, содержащий следующие поля:

• paging, которое содержит поля:

  • previous – url предыдущей страницы
  • next – url следующей страницы
  • results_count – общее количество объектов на всех страницах

• data – контейнер для данных

При выдаче элементов 1-ой страницы отсутствует поле previous, а последней - поле next соответственно. В случае, когда результирующий список элементов помещается на 1 страницу, словарь paging будет содержать только поле results_count.

{
  "paging": {
    "previous": "https://biz.mail.ru/api/domains/1/users?limit=25&offset=0",
    "results_count": 26
  },
  "data": [
    {
      "id": 14423,
      "username": "alex",
      "email": "alex@test.com",
      "nick": null,
      "firstname": "Алексей",
      "lastname": "Пупкин",
      "groups": [
        {
          "id": 3241,
          "name": "programmers"
        }
      ],
      "avatars": {
        "90x90": "//filin.mail.ru/pic?width=90&height=90&email=alex@test.com"
      },
      "created_at": "2013-01-09T12:03:28Z",
      "status": "active",
      "status_at": "2013-01-09T12:03:28Z"
    }
  ]
}

Авторизация¶

Авторизация клиентов API выполняется на основе протокола авторизации OAuth 2.0. В каждом запросе помимо параметров вызываемого метода следует передавать access token. Процедуры получения и обновления access token описаны в главе “OAuth 2.0 Авторизация”.

curl "https://biz.mail.ru/api/v1/domains" -H "Authorization: Bearer 5c918ed51f38749782b8b2c3ad41a265e560661137363830"

GET /api/v1/domains
Authorization: Bearer 5c918ed51f38749782b8b2c3ad41a265e560661137363830
Host: biz.mail.ru

Ошибки клиента¶

В случае ошибок клиента возвращается ответ с HTTP-кодом 400.

HTTP 400 BAD REQUEST

{
  "code": 0,
  "message": "Ошибка валидации данных.",
  "data":  {
    "name": ["Недопустимое имя домена"]
  }
}

HTTP 403 FORBIDDEN

{
  "message": "Authentication credentials were not provided."
}

Действующие ограничения¶

• Любые запросы с одного IP-адреса (не более 200 запросов в минуту)
• Запросы на добавление домена (не более 50 запросов в минуту)