Документация API клиентского приложения

Общее описание API:
Формирование запроса
Описание ответа
Работа с формами
Отправка формы

Работа с пользователем:
Авторизация пользователя (http)
Запрос авторизованным пользователем (http)
Выход пользователя (http)

Список сигнализаций:
Получение списка сигнализаций (http)
Авторизация на сервере сокетов для просмотра списка сигнализаций (ws)

Данные сигнализации:
Получение данных сигнализации (http)
Авторизация на сервере сокетов для просмотра данных сигнализации (ws)
Обновление состояния сигнализации (ws)

Данные сигнализации со списком логов:
Получение данных сигнализации и списка логов (http)
Авторизация на сервере сокетов для просмотра данных сигнализации и списка логов (ws)

Общее описание API
API представляет собой готовый набор методов обмена данными с сервером pride.gudsoft.ru.
Весь механизм обмена данными с сервером строится на двух типах запросов: GET и POST.

- Формирование запроса
POST-запрос к серверу формируются следующим образом:
Код:http://pride.gudsoft.ru/api/[route][get]
{
post
}
где:
route - роут;
get - get-параметры запроса;
post - post-параметры запроса;

Данные от сервера возвращаются в JSON-формате и кодировке UTF-8.

- Описание ответа
Рассмотрим простой запрос:Код:http://pride.gudsoft.ru/apiСервер вернёт ответ в следующем формате:Код:{"data":null,"forms":null,"user":null,"message":"Ошибка выполнения запроса","messageType":"danger","version":"1.0"}Для отладки и визуального просмотра ответа от сервера, можно использовать запрос с get-параметром fout=1:
Код:http://pride.gudsoft.ru/api/?fout=1Сервер вернёт ответ в следующем формате:Код:fusion\entity\FApiEntity Object
(
[data] =>
[forms] =>
[user] =>
[message] => Ошибка выполнения запроса
[messageType] => danger
[version] => 1.0
)

Рассмотрим данные ответа:
data - объект содержит список возвращаемых данных, например, данные сигнализации. обратите внимание, массив data содержит не сами данные, а наборы вложенных данных, к примеру, alertData.
forms - объект списка форм. если в ответе не содержится формы модели, данное поле будет пустым.
user - данные авторизованного пользователя. если поле пустое, значит текущий пользователь не авторизован.
message - текст сообщения.
messageType - тип текста сообщения (danger, success, info).
version - текущая версия API

Запрос можно считать успешным, если message пустой. Иначе можно вывести сообщение с информацией из message.

Также в заголовке приходит код состояния:
200 - запрос выполнен успешно;
302 - сработала переадресация, чаще всего с сообщением об ошибке message; если message пустой, то запрос выполнен успешно;
404 - страница не найдена;
500 - возникла внутренняя ошибка сервера;

- Работа с формами
Для примера, рассмотрим форму авторизации пользователя. Отправим запрос
Код:http://pride.gudsoft.ru/api/user/loginответ от сервераДанные приходят в json-формате. Видим, в объекте forms содержится список форм текущей страницы. В нашем случае - forms[User], где User - название модели пользователя.
Форма содержит список полей forms[User][fields], которые могут быть обработаны. У каждого поля есть параметры label и value, которые отвечают за название поля и его значение соответственно. Значение может быть задано как по-умолчанию, на сервере, так и вернуться в ответ, после отправки формы.
Также, форма содержит список ошибок forms[User][errors], в случае, если они возникли при валидации формы.
Переменная forms[User][isSubmit] содержит информацию, отправлена ли форма для валидации на сервер.

- Отправка формы
Отправка формы осуществляется post-запросом. Для примера, отправим запрос на авторизацию пользователя:
Код:http://pride.gudsoft.ru/api/user/login
{
User[login]: "ваш логин",
User[password]: "ваш пароль"
}
После валидации формы, мы получаем ответ от сервера, аналогичный предыдущему пункту документации, где в объекте forms[User][errors] видим список ошибок в полях формы:
Код:[errors] => stdClass
(
[login] => Неправильное имя пользователя или пароль
)
В случае, успешной отправки формы, forms[User][isSubmit] будет true, а объект forms[User][errors] будет пустым.

Важно! Если возникают проблемы с отправкой формы, проверьте наличие следующего заголовка в запросе:Код:"Content-Type": "application/x-www-form-urlencoded"

Работа с пользователем
- Авторизация пользователя (http)
Для авторизации пользователя, необходимо отправить post-запрос на следующий адрес:
Код:http://pride.gudsoft.ru/api/user/login
{
User[login]: "ваш логин",
User[password]: "ваш пароль"
}

Логином может служить как логин, так и e-mail пользователя. В случае успешной валидации формы, в ответе от сервера, мы получим подобные данные в объекте user:Код:user =>
(
id => 1,
login => Sony,
role => admin,
status => active,
lang => ru,
access => null,
isUser => true,
isModer => true,
isOperator => true,
isManager => true,
isAdmin => true,
fauth => u9hVnqXmPvXSCVlv....3qD2MNYgLr/W+DLZ5
)
где
id - идентификатор пользователя.
login - логин пользователя.
role - роль пользователя (user|moder|manager|admin).
status - статус пользователя (new|active|block|delete)
fauth - ключ авторизации API.
Остальные данные объекта user в текущем проекте не используются.

Обратите внимание на ключ авторизации. С помощью него необходимо отправлять следующие запросы на сервер для просмотра страниц авторизованным пользователем.

- Запрос авторизованным пользователем (http)
Для отправки запроса авторизованным пользователем, необходимо использовать ключ авторизации из переменной fuath. Ключ передаётся в post-запросе:
Код:http://pride.gudsoft.ru/api/alert/index
{
fuath: "ключ авторизации api"
}

После выполнения запроса, система вернёт новый ключ, который нужно будет использовать при формировании следующего запроса к API.
Важно знать, ключ имеет срок действия и может протухнуть по таймауту. В этом случае, нужно будет заново авторизоваться для получения нового ключа доступа.

В простой форме, алгоритм посещения сайта авторизованным пользователем будет выглядеть следующим образом:
1. Авторизуемся на /api/user/login и получаем ключ доступа fauth. Введённые данные сохраняем в storage.
2. Посылаем post-запрос с ключом авторизации fauth, например на /api/alert/index
3. Если ключ некорректный и система требует авторизации, выполняем пункт 1, затем 2. Если пункт 2 не выполнился (например, юзера через веб-интерфейс изменил пароль на сайте), то показываем форму авторизации.

- Выход пользователя (http)
Для выхода пользователя, необходимо отправить post-запрос на следующий адрес:
Код:http://pride.gudsoft.ru/api/user/logout
{
fuath: "ключ авторизации api"
}
После этого, будет удалён токен авторизации в системе.

Список сигнализаций
- Получение списка сигнализаций (http)
Для получения списка сигнализаций отправляем следующий post-запрос:
Код:http://pride.gudsoft.ru/api/alert/index
{
fuath: "ключ авторизации api"
}
При корректном ответе, получим ответ от сервера с объектом data
Код:"data":{
"alertList":[
{
"id": "1",
"title": "Тестовая Sony",
"address": "улица Пушкина, дом Колотушкина",
"state": "1",
"isOnline": "1",
"dateUpdate": "2017-05-10 16:55:01"
}
],
"stateList":{
"1": "на охране",
"2": "снят с охраны",
"3": "тревога: движение",
"4": "тревога: пожар",
"5": "тревога: утечка газа",
"6": "тревога: шум"
},
"token": "xxx",
"socketId": "1067"
},

alertList - массив объектов сигнализаций, где
id - идентификатор сигнализации,
title - название
address - адрес (при отсутствии адреса - null)
state - состояние
isOnline - присутствует ли коннект к сервисному приложению
dateUpdate - дата последнего обновления
stateList - список доступных состояний
token - токен для авторизации на сервере сокетов
socketId - id сокета для авторизации на сервере сокетов

- Авторизация на сервере сокетов для просмотра списка сигнализаций (ws)
После выполнения http-запроса на получение данных, сервер возвращает token и socketId для авторизации на сервере сокетов. Для этого, выполним запрос Код:ws://pride.gudsoft.ru:8082
{
action: "app/alert/index",
token: "токен",
socketId: "id коннекта"
}
token и socketId используем те, которые получили при отправке http-запроса. После успешной авторизации, сокет вернёт ответ в следующем формате: Код:{
"status": "open"
}
Теперь от сервера сокетов могут прийти данные на обновление списка сигнализацийКод:{
"data":{
"alertList":[
{
"id": "1",
"title": "Тестовая Sony",
"address": "улица Пушкина, дом Колотушкина",
"state": "1",
"isOnline": "1",
"dateUpdate": "2017-05-10 16:55:01"
}
],
},
"message": null
}
Рассмотрим данные ответа:
data.alertList - список сигнализаций в формате получения списка сигнализаций (http)
message - текст сообщения при ошибке.

Данные сигнализации
- Получение данных сигнализации (http)
Для получения данных сигнализации отправляем следующий post-запрос:
Код:http://pride.gudsoft.ru/api/alert/view?id=XXX
{
fuath: "ключ авторизации api"
}
где XXX - id сигнализации.
При корректном ответе, получим ответ от сервера с объектом data
Код:"data":{
"alertData": {
"id": "1",
"title": "Тестовая Sony",
"address": "улица Пушкина, дом Колотушкина",
"state": "1",
"isOnline": "1",
"dateUpdate": "2017-05-10 16:55:01",
"emailList": [],
"phoneList": []
},
"token": "xxx",
"socketId": "1067"
},

alertData - данные сигнализации, где
id - идентификатор сигнализации,
title - название
address - адрес (при отсутствии адреса - null)
state - состояние
isOnline - присутствует ли коннект к сервисному приложению
dateUpdate - дата последнего обновления
emailList - список e-mail уведомлений
phoneList - список телефонов уведомлений
token - токен для авторизации на сервере сокетов
socketId - id сокета для авторизации на сервере сокетов

- Авторизация на сервере сокетов для просмотра данных сигнализации (ws)
После выполнения http-запроса на получение данных, сервер возвращает token и socketId для авторизации на сервере сокетов. Для этого, выполним запрос Код:ws://pride.gudsoft.ru:8082
{
action: "app/alert/view",
token: "токен",
socketId: "id коннекта"
}
token и socketId используем те, которые получили при отправке http-запроса. После успешной авторизации, сокет вернёт ответ в следующем формате: Код:{
"status": "open"
}
Теперь от сервера сокетов могут прийти данные на обновление данных сигнализацииКод:{
"data":{
"alertData": {
"id": "1",
"title": "Тестовая Sony",
"address": "улица Пушкина, дом Колотушкина",
"state": "1",
"isOnline": "1",
"dateUpdate": "2017-05-10 16:55:01"
},
},
"message": null
}
Рассмотрим данные ответа:
data.alertData - данные сигнализации в формате получения данных сигнализации (http)
message - текст сообщения при ошибке.

- Обновление состояния сигнализации (ws)
Для изменения состояния сигнализации, нужно быть авторизованным в сокете. После этого, выполняем запрос Код:ws://pride.gudsoft.ru:8082
{
action: "app/alert/update",
id: XXX,
state: YYY
}
Где id - идентификатор сигнализации, state - состояние. Состояние может принимать одно из следующих значений:
1: "на охране",
2: "снят с охраны",
3: "тревога: движение",
4: "тревога: пожар",
5: "тревога: утечка газа",
6: "тревога: шум"

Данные сигнализации и список логов
- Получение данных сигнализации и списка логов (http)
Для получения данных сигнализации и списка логов отправляем следующий post-запрос:
Код:http://pride.gudsoft.ru/api/alert/log/index?alert=XXX
{
fuath: "ключ авторизации api"
}
где XXX - id сигнализации.
При корректном ответе, получим ответ от сервера с объектом data
Код:"data":{
"alertData": {
"id": "1",
"title": "Тестовая Sony",
"address": "улица Пушкина, дом Колотушкина",
"state": "1",
"isOnline": "1",
"dateUpdate": "2017-05-10 16:55:01",
"emailList": [],
"phoneList": []
},
"logList": [],
"stateList":{
"1": "на охране",
"2": "снят с охраны",
"3": "тревога: движение",
"4": "тревога: пожар",
"5": "тревога: утечка газа",
"6": "тревога: шум"
},
"token": "xxx",
"socketId": "1067"
},

alertData - данные сигнализации, где
id - идентификатор сигнализации,
title - название
address - адрес (при отсутствии адреса - null)
state - состояние
isOnline - присутствует ли коннект к сервисному приложению
dateUpdate - дата последнего обновления
emailList - список e-mail уведомлений
phoneList - список телефонов уведомлений
logList - список логов сигнализации
stateList - список доступных состояний
token - токен для авторизации на сервере сокетов
socketId - id сокета для авторизации на сервере сокетов

- Авторизация на сервере сокетов для просмотра данных и списка логов сигнализаций (ws)
После выполнения http-запроса на получение данных, сервер возвращает token и socketId для авторизации на сервере сокетов. Для этого, выполним запрос Код:ws://pride.gudsoft.ru:8082
{
action: "app/alert/log/index",
token: "токен",
socketId: "id коннекта"
}
token и socketId используем те, которые получили при отправке http-запроса. После успешной авторизации, сокет вернёт ответ в следующем формате: Код:{
"status": "open"
}
Теперь от сервера сокетов могут прийти данные на обновление данных сигнализации и списка логовКод:{
"data":{
"alertData": {
"id": "1",
"title": "Тестовая Sony",
"address": "улица Пушкина, дом Колотушкина",
"state": "1",
"isOnline": "1",
"dateUpdate": "2017-05-10 16:55:01"
},
"logList": [],
},
"message": null
}
Рассмотрим данные ответа:
data.alertData - данные сигнализации в формате получения данных сигнализации (http)
data.logList - список лога сигнализаций.
message - текст сообщения при ошибке.

Протестировать запросы с ответами к серверу можно через эмулятор клиентского приложения.