Введение

Доступ к MadBanner REST API осуществляется по протоколу HTTP. API доступно по адресу вида http://api.example.com/. Для уточнения адреса обратитесь к администратору.

$ curl --request GET \
       --include \
       --user "admin:admin" \
       --url http://api.example.com/users/admin

HTTP/1.1 200 OK
Server: nginx/1.4.3
Date: Mon, 11 Nov 2013 14:10:25 GMT
Content-Type: application/json
Content-Length: 64
Connection: keep-alive

{
  "id":"admin",
  "email":"admin@example.com",
  "name":"Chuck Norris"
}

Формат представления данных

В качестве формата представления данных используется JSON.

В HTTP-запросах, содержащих JSON-документ, следует явно указывать тип данных в HTTP-заголовке Content-Type:

Content-Type: application/json

В большинстве случаев POST-запросы должны содержать JSON-документ в теле запроса, а GET и DELETE - нет.

Операции над ресурсами

В большинстве случаев управление обьектом осуществляется с помощью двух HTTP-ресурсов. Например для управления пользователями предусмотрены следующие ресурсы:

  • /users - создание ресурса, поиск ресурсов
  • /users/:id - чтение, изменение, удаление ресурса

Например:

Метод Ресурс Результат
POST /users создать пользователя
GET /users найти пользователей
GET /users/:id получить данные пользователя
POST /users/:id изменить данные пользователя
DELETE /users/:id удалить пользователя

Поиск

Запрос для осуществления поиска может принимать следующие параметры:

Параметр Значение Описание Пример
limit Целое число Кол-во обьектов в выдаче GET /users?limit=42
offset Целое число Пропустить первые N обьектов в выдаче GET /users?offset=42
order_by Поле обьекта Отсортировать выдачу по ключу. Значение по умолчанию id [1] GET /users?order_by=id
order ASC или DESC Порядок сортировки GET /users?order=desc
<key> Поле обьекта Найти обьекты с полями <key>=<value> [1] GET /users?id=admin

Порядок параметров не важен; запрос может содержать несколько параметров:

GET /users?limit=42&offset=42&order_by=id&order=asc

[1] Значение полей order_by и <key> может содержать лишь некоторые поля ресурса. Список разрешенных для сортировки полей указан в описании ресурса (см. колонку Фильтр).

Аутентификация

Доступ к только что установленной системе осуществляется под пользователем admin (пароль по умолчанию: madpassword). Пользователь admin имеет право на выполнение всех без исключения операций. Сразу после установки MadBanner рекомендуется сменить пароль на более стойкий.

Каждый запрос должен содержать заголовок Authorization с именем пользователя и паролем, закодированными с помощью Base64. См. Basic Authentication

Так для пользователя с именем “admin” и паролем “admin” необходимо передать заголовок:

Authorization: Basic YWRtaW46YWRtaW4=
$ curl --request GET \
       --include \
       --header "Authorization: Basic YWRtaW46YWRtaW4=" \
       --url http://api.example.com/users/admin


HTTP/1.1 200 OK
Server: nginx/1.4.3
Date: Mon, 11 Nov 2013 14:11:55 GMT
Content-Type: application/json
Content-Length: 64
Connection: keep-alive

{
  "id":"admin",
  "email":"admin@example.com",
  "name":"Chuck Norris"
}

HTTPS

Чтобы обеспечить защищенность передаваемых данных, следует обращаться к API по протоколу HTTPS. HTTPS API доступно по адресу вида https://api.example.com/

Для работы с HTTPS API необходим сертификат: загрузить madbanner.crt

Пример:

$ curl --request GET \
       --include \
       --cacert "./madbanner.crt" \
       --user "admin:admin" \
       --url https://api.example.com/users/admin

HTTP/1.1 200 OK
Server: nginx/1.4.3
Date: Mon, 11 Nov 2013 10:05:41 GMT
Content-Type: application/json
Content-Length: 64
Connection: keep-alive

{
  "id":"admin",
  "email":"admin@example.com",
  "name":"Chuck Norris"
}

Формат ошибок

В общем случае при возникновения ошибки, сервер возвращает код 4XX или 5XX и JSON-документ с подробным описанием ошибки:

$ curl --request GET \
       --include \
       --user "admin:admin" \
       --url http://api.example.com/users/alice

HTTP/1.1 404 Not Found
Server: nginx/1.4.3
Date: Mon, 11 Nov 2013 09:46:57 GMT
Content-Type: application/json
Content-Length: 81
Connection: keep-alive

{
  "error":"object_not_found",
  "message":"resource with id=<<\"alice\">> not found"
}

Формат представления времени

Все даты передаются в формате ISO 8601:

YYYY-MM-DDTHH:MM:SS±HH:MM
YYYY-MM-DDTHH:MM:SS±HHMM
YYYY-MM-DDTHH:MM:SS±HH
YYYY-MM-DDTHH:MM:SSZ

Пример:

2014-10-15T12:00:00+03:00
2014-10-15T12:00:00+0300
2014-10-15T12:00:00+03
2014-10-15T12:00:00-03
2014-10-15T12:00:00Z