===== Описание протокола REST API =====

==== Общие настройки ====

Протокол предназначен для обмена данными с устройствами и сторонними системами сбора данных, подключаемых по шине REST API. Обмен данными осуществляется в формате JSON.

**Подключение к серверу системы мониторинга по протоколу REST API**

Для подключения к серверу системы мониторинга по протоколу REST API используется //http//-протокол соединения. В //http//-адресе нужно указать домен или IP-адрес сервера. Например:
<code>
http://[Домен или IP адрес]/api/[Параметр запроса]

</code>

На сервере поддерживается два типа запроса:

  * GET-запрос для получения данных из системы мониторинга;

  * POST-запрос для записи данных в систему мониторинга.

**Регистрация устройств и сторонних систем сбора данных по протоколу REST API**

Для авторизации необходимо указать API-токен. Токен указан в настройках Пользователя. Для того, чтобы токен работал, в настройках Пользователя должен быть включен чек-бокс «Доступ к API».

{{:документация:описание_протокола_rest_api:rest_api_токен_.jpg?200|}}

Для запроса данных необходимо использовать GET-запрос с параметром «Authorization» в заголовке запроса. В адресной строке в качестве GET-параметра указать API-токен. Например:

<code>
http://[SERVER]/api/[Параметр_запроса]?api_token=hBI4O8rClizALOPcrJ4DbljhHS8cVthn)

</code>

Для отправки данных на сервер создать POST-запрос одним из трех способов:

1. В адресной строке в качестве GET-параметра указать API-токен. Например:

<code>
http://[SERVER]/api/[Параметр_запроса]?api_token=hBI4O8rClizALOPcrJ4DbljhHS8cVthn)

</code>

2. В теле запроса указать параметр API-токен

3. В заголовке запроса («Bearer») указать параметр «Authorization», значение «Bearer» ''hBI4O8rClizALOPcrJ4DbljhHS8cVthn''.

**Синхронизация времени сервера и источника данных**

Для синхронизации времени формируется запрос метки времени, который возвращает текущее время сервера в формате JSON. Параметр GET запроса – «''timestamp''». Время указано в формате GMT.

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

<code>
http://[SERVER]/api/timestamp?api_token=hBI4O8rClizALOPcrJ4DbljhHS8cVthn

</code>

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

<code>
{
"code":200,
"status":"success",
"data":{
  "timestamp":1660039669
       }
}

</code>

==== Запросы ====

**Запрос списка шин**

Запрос списка шин формируется для отображения параметров активных шин в системе. Параметр GET запроса – «''/buses''».

Таблица 1.

^  Параметр в JSON^Поле в системе мониторинга|
|//id// |Уникальный номер шины в системе мониторинга|
|//code// |Код шины|
|//comment// |Комментарий|
|//tcp_remote_address// |IP-адрес (Конвертор, OPC Gateway Service, XNB mqtt URL)|
|//tcp_port// |Порт сервера|
|//bus_type// |Тип шины|
|//enabled/disabled// |Шина включена/выключена|

Пример запроса:
<code>

http://[SERVER]/api/buses?api_token=hBI4O8rClizALOPcrJ4DbljhHS8cVthn

</code>

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

<code>
{
"code": 200,
"status": "success",
"data": [{
    "id": 1,
    "code": "rest1",
    "comment": null,
    "tcp_remote_address": null,
    "tcp_port": null,
    "bus_type": "restapijson",
    "enabled": true
    }]
}

</code>

**Запрос информации по выбранной шине**

Для получения параметров шины и списка устройств необходимо сформировать GET-запрос «''/buses/{buse_code}''».

Для выбора шины необходимо указать «''code''» (код шины) вместо переменной «''{buse_code}''». Входные данные на запрос содержат информацию по запрошенной шине (см. Таблица 1) и информацию по всем устройствам, подключенным к шине (см. Таблица 2).

Таблица 2.

^Параметр в JSON (массив значений: //device//)^Поле в системе мониторинга|
|//id// |Уникальный номер устройства в системе мониторинга|
|//code// |Код устройства|
|//device_type// |Тип устройства|
|//comment// |Комментарий|
|//active_metering_period// |Периодичность опроса устройства, секунд|
|//auto_metering_period// |Периодичность сеансов измерений, секунд|
|//correction_angle// |Коррекция азимута, градус|
|//correction_reverse// |Система координат|

Пример запроса:
<code>

http://[SERVER]/api/buses/rest1?api_token=hBI4O8rClizALOPcrJ4DbljhHS8cVthn

</code>

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

<code>
{
"code": 200,
"status": "success",
"message": "Information on devices and buses"
"data": {
    "id": 1,
    "code": "rest1",
    "comment”: "",
    "tcp_remote_address": "192.168.0.1",
    "tcp_port": 0,
    "bus_type": "restapijson",
      "device1": {
          "id": 1,
          "code": "test1"
          "device_type": "Спектроанализатор",
          "comment": "",
          "active_metering_period": 600,
          "auto_metering_period": 60,
          "correction_angle": 0,
          "correction_reverse": 0
          }
    }
}

</code>

**Запрос информации по выбранному устройству**

Для получения параметров устройства и списка каналов необходимо сформировать GET-запрос «''/sensors/{device_code}''».

Для выбора устройства необходимо указать «''code''» (код устройства) вместо переменной «''{device_code}''». Входные данные на запрос содержат информацию по шине (см. Таблица 1), запрошенному устройству (см. Таблица 2) и информацию по всем каналам выбранного устройства (см. Таблица 3).

Таблица 3.

^Параметр в JSON (массив значений: //channels//)^Поле в системе мониторинга|
|//id// |Уникальный номер канала в системе мониторинга|
|//sensor_id// |Уникальный номер устройства в системе мониторинга|
|//addr// |Адрес|
|//code// |Код канала|
|//height// |Высотная отметка, м|
|//correction_ratio// |Коэффициент преобразования|
|//correction// |Смещение 0|

Пример запроса (запрос возвращает данные за последние 24 часа):
<code>

http://[SERVER]/api/sensors/test1?api_token=hBI4O8rClizALOPcrJ4DbljhHS8cVthn

</code>

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

<code>
{
"code": 200,
  "status": "success",
  "data": {
      "id": 1,
      "bus_id": 1,
      "code": "test1",
      "device_type": "spectroanalyzer",
      "comment": null,
      "active_metering_period": "600.00",
      "auto_metering_period": "0.0000",
      "correction_angle": "0",
      "correction_reverse": false,
      "enabled": true,
      "channels": [{
          "id": 1,
          "sensor_id": 1,
          "addr": "t1",
          "code": "t1",
          "height": "0",
          "correction_ratio": null,
          "correction": "0"
      }, {
          "id": 2,
          "sensor_id": 1,
          "addr": "t2a",
          "code": "t2c",
          "height": "0",
          "correction_ratio": null,
          "correction": "0"
      }],
      "bus": {
          "id": 1,
          "code": "rest1",
          "tcp_remote_address": "62.213.109.66",
          "tcp_port": 0,
          "bus_type": "restapijson",
          "enabled": true,
          "comment": null
      }
    }
 }

</code>

**Запрос данных измерения по выбранному Каналу**

Для получения информации об измерениях за выбранный период времени необходимо сформировать GET-запрос «''/channels_data/{channel_id}''».

Для выбора канала необходимо указать «''id''» (уникальный номер канала в Системе Мониторинга) вместо переменной «''{channel_id}''». Входные данные на запрос содержат информацию данных в выбранном канале (см. Таблица 4).

Таблица 4.

^Параметр в JSON^Поле в системе мониторинга|
|//dateFrom// |Дата начала запрошенного периода|
|//dateTo// |Дата окончания запрошенного периода|
|//values→time// |Время измерения|
|//values→val// |Значения измерения|

Пример запроса:
<code>

http://[SERVER]/api/channels_data/2?api_token=hBI4O8rClizALOPcrJ4DbljhHS8cVthn

</code>

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

<code>
{
"code": 200,
"status": "success",
"data": {
    "dateFrom": "2022-08-09 20:14:35",
    "dateTo": "2022-08-10 20:14:35",
    "values": [{
      "time": 1660058075,
      "val": null
        , {
      "time": 1660058675,
      "val": null
        }, {
      "time": 1660115343,
      "val": null
      "time": 1660116283,
      "val": 160
        }, {
      "time": 1660144475,
      "val": null
      }]
    }
}

</code>

**Запрос статусов по объекту мониторинга**

Для получения статусов по каналам (сигнализации) на объекте мониторинга необходимо сформировать GET-запрос «''/objects_status/{object_id}''».

Для выбора объекта мониторинга укажите «''id''» (уникальный номер объекта мониторинга в Системе) вместо переменной «''{object_id}''». Входные данные на запрос содержат информацию по объекту мониторинга (см. Таблица 5).

Таблица 5.

^Параметр в JSON^Поле в системе мониторинга| 
|//id// |Уникальный номер объекта мониторинга| 
|//title// |Название объекта| 
|//interval// |Интервал, секунды (для внешних систем)| 
|//date// |Дата и время запроса данных| 
|//enabled_buses→bus_id// |Уникальный номер шины| 
|//enabled_buses→name// |Название шины| 
|//enabled_buses→code// |Код шины| 
|//enabled_sensors→sensor_id// |Уникальный номер устройства| 
|//enabled_sensors→name// |Название устройства| 
|//enabled_sensors→code// |Код устройства| 
|//channels→channel_id// |Уникальный номер канала| 
|//channels→name// |Название канала| 
|//channels→code// |Код канала| 
|//channels→state// |Статус| 

Пример запроса:
<code>

http://[SERVER]/api/objects_status/{object_id}?api_token=hBI4O8rClizALOPcrJ4DbljhHS8cVthn

</code>

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

<code>
{
"code": 200,
"status": "success",
"data": {
    "id": 1,
    "title": "Название объекта",
    "interval": 15,
    "date": "2022-10-03 22:24:34",
    "enabled_buses": [{
      "bus_id": 1,
      "name": "REST API (JSON)",
      "code": "rest1",
      "enabled_sensors": [{
        "sensor_id": 1,
        "name": "Название устройства",
        "code": "Код устройства",
        "channels": [{
          "channel_id": 1,
          "name": "Название канала",
          "code": "Код канала",
          "state": "gray"
          }, {
          "channel_id": 2,
          "name": "Название канала",
          "code": "Код канала",
          "state": "gray"
        }]
        },{
        "sensor_id": 2,
        "name": "RestAPI 2",
        "code": "test2",
        "channels": [{
           "channel_id": 3,
           "name": "T1",
           "code": "t1",
           "state": "red"
         }, {
           "channel_id": 4,
           "name": "T2",
           "code": "t2c",
           "state": "green"
         }]
     }, ....

</code>

**Запрос элементов конструкции по объекту мониторинга**

Для получения информации о параметрах конструктивных элементов и сигнализации по каналам на объекте мониторинга необходимо сформировать GET-запрос «''object_elements/{object_id}''». Для выбора объекта мониторинга укажите «''id''» (уникальный номер объекта мониторинга в Системе) вместо «''{object_id}''». Назначение параметров в JSON-формате – см. Таблица 6.

Таблица 6.

^Параметр в JSON^Поле в системе мониторинга|
|//location_id// |Уникальный номер ОМ|
|//location_title// |Название объекта мониторинга|
|//location_code// |Код объекта мониторинга|
|//elements→id// |ID элемента|
|//elements→bus_id// |Уникальный номер шины|
|//elements→_lft// |Параметр для построения дерева элемента конструкции|
|//elements→_rgt// |Параметр для построения дерева элемента конструкции|
|//elements→parent_id// |Параметр для построения дерева элемента конструкции|
|//elements→title// |Название элемента|
|//elements→type// |Тип элемента|
|//elements→code// |Код элемента|
|//elements→description// |Описание элемента|
|//elements→state// |Категория технического состояния|
|//elements→sensors// |Параметры устройства, привязанного к элементу|
|//elements→sensor_channels// |Параметры Канала, привязанного к элементу|

Пример запроса:
<code>

http://[HOSTNAME]/api/object_elements/{object_id}?api_token=1I18lUJW0lIiBjE0zvSeum3TSs06vcKi

</code>

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

<code>
{
"code": 200,
"status": "success",
"data": {
      "location_id": 1,
      "location_title": "1",
      "location_code": null,
      "elements": [{
          "id": 9,
          "_lft": 2,
          "_rgt": 5,
          "parent_id": 1,
          "title": "L1E1",
          "type": "",
          "code": "l1e1",
          "description": null,
          "state": "",
          "sensors": [{
              "id": 8,
              "name": "A1.1 X",
              "code": "8",
              "enabled": true,
              "channels": [{
                  "channel_id": 26,
                  "name": "1 d1",
                  "code": "d1",
                  "state": "gray"
              },  {
                  "channel_id": 34,
                  "name": "5 f5-2",
                  "code": "f5-2",
                  "state": "gray"
              }]
          }],
          "sensor_channels": [{
              "channel_id": 26,
              "sensor_id": 8,
              "name": "1 d1",
              "code": "d1",
              "enabled": true,
              "state": "gray"
          }]
      }, {
          "id": 15,
          "_lft": 9,
          "_rgt": 10,
          "parent_id": 14,
          "title": "L1E2222",
          "type": “",
          "code": "l1e2222",
          "description": null,
          "state": "",
          "sensors": [{
              "id": 9,
              "name": "A1.1 Z",
              "code": "9",
              "enabled": true,
              "channels": [{
                  "channel_id": 41,
                  "name": "1  d1",
                  "code": "d1",
                  "state": "gray"
              }, {
                  "channel_id": 42,
                  "name": "1 f1",
                  "code": "f1",
                  "state": "gray"
              },  {
                  "channel_id": 48,
                  "name": "5  f5",
                  "code": "f5",
                  "state": "gray"
              }, {
                  "channel_id": 49,
                  "name": "5  f5-2",
                  "code": "f5-2",
                  "state": "gray"
              }]
          }],
          "sensor_channels": []
      }]
  }
}

</code>

==== Запись данных по протоколу ====

Запись данных в базу данных Систему Мониторинга осуществляется при условии, что для устройства выбран тип шины «REST API (JSON)».

Для записи данных необходимо сформировать POST-запрос «''/sensors_data/ {device_code}''».

Для выбора устройства укажите «''code''» (код устройства) вместо переменной «''{device_code}''». Данные запроса для записи в базу данных содержат информацию по каналу выбранного устройства (см. Таблица 7).

Таблица 7.

^Параметр в JSON^Поле в системе мониторинга|
|//api_token// |Токен для доступа к API|
|//timestamp// |Время измерения|
|//data→addr// |Адрес канала|
|//data→value// |Значения измерения|

Пример адреса для POST запроса:
<code>

http://[SERVER]/api/sensors_data/test1

</code>

Пример JSON-формата, где параметр ''data''  – строковое значение:

<code>
{
"api_token": "hBI4O8rClizALOPcrJ4DbljhHS8cVth",
"timestamp": 1659696538,
"data": “[{\"addr\": \"t1\", \"value\": 12}, {\"addr\": \"t2a\",\"value\": 22}]”

</code>

==== Сообщения об ошибках в протоколе ====

А. Ответ при отсутствии ID объекта мониторинга при запросе списка элементов:

<code>
{
"code": 404,
"status": "error",
"message": "Object with this id was not found.",
"data": {
    "object_id": 15
        }
}

</code>

Б. Ответ при отключении пользователя (чек-бокс «Доступ к API» выключен у Пользователя):

<code>
{
"code": 404,
"status": "error",
"message": "Device with this code was not found.",
"data": {
     "device_code": "test3"
        }
}

</code>

В. Ответ при неверном API-Токене:

<code>
{
"code": 401,
"status": "error",
"message": "Unauthenticated."
}

</code>

Г. Не найдена шина в системе мониторинга:

<code>
{
"code": 404,
"status": "error",
"message": "Bus with this code was not found.",
"data": {
      "bus_code": "rest2"
        }
}

</code>

Д. При записи данных протокол обмена указан неверно (не «REST API (JSON)»):

<code>
{
"code": 403,
"status": "error",
"message": "Bus type must be REST API (JSON).",
"data": {
      "bus_code": "rest1"
        }
}

</code>

Е. Шина выключена или не создана:

<code>
{
"code": 403,
"status": "error",
"message": "The bus is off.",
"data": {
      "bus_code": "rest1"
        }
}

</code>

Ж. Код устройства не найден:

<code>
{
"code": 404,
"status": "error",
"message": "Device with this code was not found.",
"data": {
      "device_code": "test3"
        }
}

</code>

З. Устройство выключено или отсутствует в системе мониторинга:

<code>
{
"code": 403,
"status": "error",
"message": "The device is off.",
"data": {
      "bus_code": "rest1",
      "sensor_code": "test1"
        }
}

</code>

И. Ответ при отсутствии записи отдельных каналов в базе данных (при этом запись в базе данных других каналов не останавливается):

<code>
{
"code": 201,
"status": "success",
"data": {
      "sensor_code": "test2",
      "answer": "Skipped addresses: ['t1v']"
        }
}  

</code>