Skip to content

REST protocol

Jump to bottom Edit New page
baden edited this page Jan 17, 2013 · 12 revisions

Наброски по протоколу обмена.

Разработка протокола перенесена сюда

Схема

Все запросы начинаются с префикса http://api.newgps.navi.cc/1.0. Далее следует путь к ресурсу. Например, получить события, относящиеся к системе с ключом :skey можно по адресу /logs/get/:skey. Полный путь будет иметь вид:

$ curl http://api.newgps.navi.cc/1.0/logs/get/KEYFORSOMESYSTEM

В большинстве запросов должен быть указан домен, с которого осуществляется запрос (CORS). Для этого должен быть установлен Origin в заголовке запроса.

$ curl -i http://api.newgps.navi.cc/1.0/info -H "Origin: http://some-site.com"

В данный момент разрешены запросы с любого домена Access-Control-Allow-Origin: *, но нужно иметь ввиду, что в дальнейшем это может быть изменено.

Передаваемые и получаемые данные имеют JSON-формат.

Параметры

Основные параметры задаются в url-пути запроса, далее запись вида :value подразумевает, что вместо :value необходимо подставить основной параметр, например в запросе DELETE http://api.newgps.navi.cc/1.0/account/systems/:skey вместо :skey необходимо указать ключ системы.

Большинство API-запросов могут содержать дополнительные параметры.

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

$ curl -i http://api.newgps.navi.cc/1.0/info?verbose=yes&state=all

Для POST-запроса, дополнительные параметры задаются в теле запроса. Если тело POST-запроса задано в JSON-формате, то должен быть установлен заголовок Content-Type: application/json; charset=utf-8.

$ curl -i -d '{"username":"baden","password":"333"}' http://api.newgps.navi.cc/1.0/login -H "Content-type: application/json;charset=UTF-8" -H "Origin: http://some-site.com"

Если запрос содержит только строковые параметры, то в качестве альтернативы может использоватьcя Content-Type: application/x-www-form-urlencoded, но предпочтение отдается application/json:

$ curl -i http://localhost:8183/1.0/login -d "username=baden&password=333" -H "Origin: http://some-site.com"

Ошибки

Если была попытка выполнения неавторизованного запроса, то будет возвращена ошибка:

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
Content-Length: 68

{
    "status_code": 401, 
    "message": "Requires authentication"
}

Пример возвращаемой ошибки при ошибке в параметрах:

HTTP/1.1 400 Bad Request
Content-Length: 69
Content-Type: application/json; charset=utf-8

{
    "status_code": 400, 
    "message": "Problems parsing JSON"
}

HTTP-Методы

Там где это возможно, используются соответствующие HTTP-методы:

  • GET - Получение ресурса
  • DELETE - Удаление ресурса
  • POST - Создание ресурса или выполнение действия над ресурсом.
  • PUT - Замена ресурса
  • PATCH - Изменение ресурса.

Авторизация

Для большинства запросов требуется авторизация. После выполнения запроса /login будет возвращен ключ авторизации access_token.

Два основных способа авторизации запроса:

  1. Указание access_token как параметра запроса:
$ curl curl -i "http://api.localhost/1.0/account?access_token=ACCESS_TOKEN" -H "Origin: http://some-site.com"
  1. Указание access_token в заголовке Authorization:
$ curl curl -i "http://api.localhost/1.0/account" -H "Origin: http://some-site.com" -H "X-Authorization: ACCESS_TOKEN"
  1. Использование печенек. Для запросов, поддерживающих Access-Control-Allow-Credentials: true будут установлены печеньки.

User Agent

Все запросы для корректной работы требуют чтобы был установлен User Agent.

Формат основных ресурсов

Формат базовых полей

  • string - Строковое значение
  • int - Целочисленное значение
  • bool - Значение истина/ложь - true/false
  • datetime - Целочисленное значение. Дата/время указывается в Unux-time формате. Количество секунд, прошедших с полуночи (00:00:00 UTC) 1 января 1970 года (четверг)
  • list - Список значений
  • dict - Словарь значений

Примечания

В имени домена

Аккаунт

Параметр Тип Пример значения Описание
username string "baden" Имя пользователя
name string "Денис" Отображаемое имя пользователя
domain string "some-site_com" Домен (символы точки '.' заменяются символом подчеркивания '_')
date datetime 1358078408 Дата регистрации аккаунта
premium datetime 1358078408 Дата окончания премиум-подписки
admin bool false Установлен в true если аккаунт имеет права администратора
skeys list ["SYSKEY1", "SYSKEY2"] Список ключей наблюдаемых систем
systems dict {"SYSKEY1": {"imei":"123"}} Словарь записей систем из списка наблюдения
config dict {} Словарь с записями конфигурации аккаунта
desc dict {} Словарь с дополнительными записями аккаунта
akey string "c29tZS1zaXRlX2NvbTo" Ключ аккаунта (более не используется)

Вход или создание акаунта

  • Путь: /login
  • Методы: POST
  • Авторизация: нет
  • Параметры запроса:
Параметр Обязателен Тип Описание
username да string имя пользователя
password да string пароль
email нет string Электронная почта
name нет string Отображаемое имя
  • Возвращаемые значения:
Параметр Тип Описание
access_token string Токен авторизации. Действителен 31 день.
account string Словарь аккаунта
result string Принимает значение "created" если вход осуществлен впервые и "already" если ранее уже производилась авторизация

Выход из акаунта

  • Путь: /logout
  • Методы: POST
  • Авторизация: да
  • Параметры запроса: нет
  • Возвращаемые значения: нет

Используется для сброса печенек при третьем методе авторизации.

Получение аккаунта

  • Путь: /account
  • Методы: GET
  • Авторизация: да
  • Параметры запроса: нет
  • Возвращаемые значения:
Параметр Тип Описание
account string Словарь аккаунта

Добавление системы

  • Путь: /account/systems
  • Методы: POST
  • Авторизация: да
  • Параметры запроса:
Параметр Тип Описание
cmd string Должно иметь значение "add"
imeis list Список "IMEI"-ев для добавляемых систем
  • Возвращаемые значения:
Параметр Тип Описание
systems list Список с записями {"result": <действие>, "system": <система>}
systems[?].result string "added" - система добавлена, "notfound" - система не найдена, "already" - система уже в списке наблюдения
systems[?].system dict Запись с информацией о системе

Изменение порядка наблюдаемых систем

  • Путь: /account/systems
  • Методы: POST
  • Авторизация: да
  • Параметры запроса:
Параметр Тип Описание
cmd string Должно иметь значение "sort"
skeys list Список ключей систем
  • Возвращаемые значения:
Параметр Тип Описание
result string В случае успешной операции значение равно "sorted"
skeys list Список ключей систем

Удаление системы из списка наблюдения

  • Путь: /account/systems/:skey

  • Методы: DELETE

  • Авторизация: да

  • Параметры запроса: нет

  • Возвращаемые значения:

Параметр Тип Описание
result string В случае успешной операции значение равно "deleted"
Add a custom footer
Add a custom sidebar

Clone this wiki locally