Довідник API користувача

Користувацький API надає механізм доступу до даних, які буферизуються в Fledge. Він призначений для того, щоб дозволити користувачам і додаткам отримати доступ до даних, які доступні в буфері, і зробити аналіз і, можливо, запустити дії, засновані на нещодавно отриманих показаннях датчиків.

Для того, щоб використовувати точки входу у користувацькому API, за винятком точки входу /fledge/authenticate, має бути автентифікований клієнт, який викликає API. Клієнт повинен надавати в кожному запиті поле заголовка authtoken, значенням якого є токен, що був отриманий за допомогою виклику /fledge/authenticate. Цей токен має бути перевірений на дійсність, а також на те, що суб'єкт, який аутентифікується, має права користувача або адміністратора.

Перегляд активів

asset

Метод активів використовується для перегляду всіх або деяких активів на основі пошуку та фільтрації.

GET all assets

GET /fledge/asset - Повертає масив кодів активів, буферизованих у Fledge, і кількість активів за кодом.

Response Payload

Масив об’єктів JSON, по одному на актив.

Назва	Тип	Опис	Приклад
count	number	Кількість записаних зчитувань для коду активу	11
assetCode	string	Код активу	asset_1

Example

$ curl -sX GET http://localhost:8081/fledge/asset
[
  {"count": 11, "assetCode": "asset_1"},
  {"count": 11, "assetCode": "asset_2"},
  {"count": 11, "assetCode": "asset_3"}
]
.

#### GET asset readings

`GET /fledge/asset/{code}` - Повертає масив зчитувань для заданого коду
активу.

**Параметри шляху**

-   **code** - код активу для отримання.

**Параметри запиту**

> -   **limit** - встановлює обмеження кількості зчитувань для
>     повернення. Якщо не вказано, за замовчуванням 20 зчитувань.
> -   **skip** - кількість активів, які потрібно пропустити. Це
>     використовується в поєднанні з лімітом і дозволяє абоненту не
>     просто отримати останні N зчитувань, але й отримати набір
>     попередніх зчитувань.
> -   **seconds** - це, по суті, альтернативна форма ліміту, але тут
>     ліміт виражається у секундах, а не у кількості зчитувань. Вона
>     поверне показники за останні N секунд. Зауважте, що його не можна
>     використовувати разом з параметрами *limit* і *skip* або з
>     параметрами запиту *hours* і *minutes*..
> -   **minutes** - це, по суті, альтернативна форма ліміту, але тут
>     ліміт виражається у хвилинах, а не у кількості зчитувань. Вона
>     поверне показання за останні N хвилин. Зауважте, що його не можна
>     використовувати разом з параметрами *limit* і *skip* або з
>     параметрами запиту *seconds* і *hours*..
> -   **hours** - це, по суті, альтернативна форма ліміту, але тут ліміт
>     виражається в годинах, а не в кількості зчитувань. Вона поверне
>     показники за останні N годин. Зауважте, що його не можна
>     використовувати разом з параметрами *limit* і *skip* або з
>     параметрами запиту *seconds* і *minutes*..
> -   **previous** - Він використовується разом з параметром запиту
>     *hours*, *minutes* або *seconds* і дозволяє користувачеві отримати
>     не лише останні показники, але й історичні дані. Значення
>     *previous* визначається в годинах, хвилинах або секундах, залежно
>     від того, з яким параметром він використовується, і визначає,
>     наскільки давно повинні закінчуватися дані, що повертаються. Якщо
>     користувач передає набір параметрів *seconds=30&previous=120*,
>     виклик поверне дані за 30 секунд, а найсвіжіші дані будуть
>     120-секундної давності.

**Response Payload**

Масив об’єктів JSON із даними зчитувань для серії зчитувань,
відсортованих у зворотному хронологічному порядку.

| Назва     | Тип         | Опис                                          | Приклад                    |
|-----------|-------------|-----------------------------------------------|----------------------------|
| reading   | JSON object | Об’єкт зчитування JSON, отриманий від датчика | `{"pressure": 885.7}`        |
| timestamp | timestamp   | Час, коли отримано показання                  | 2023-04-14 12:04:34.603963 |

**Example**

``` console
$ curl -sX GET http://localhost:8081/fledge/asset/asset_3
[
  {"reading": {"pressure": 885.7}, "timestamp": "2023-04-14 12:04:34.603963"},
  {"reading": {"pressure": 846.3}, "timestamp": "2023-04-14 12:02:39.150127"},
  {"reading": {"pressure": 913.0}, "timestamp": "2023-04-14 12:02:26.616218"},
  {"reading": {"pressure": 994.7}, "timestamp": "2023-04-14 12:02:11.171338"},
  {"reading": {"pressure": 960.2}, "timestamp": "2023-04-14 12:01:56.979426"}
]
$

$ curl -sX GET http://localhost:8081/fledge/asset/asset_3?limit=3
[
  {"reading": {"pressure": 885.7}, "timestamp": "2023-04-14 12:04:34.603963"},
  {"reading": {"pressure": 846.3}, "timestamp": "2023-04-14 12:02:39.150127"},
  {"reading": {"pressure": 913.0}, "timestamp": "2023-04-14 12:02:26.616218"}
]
.

Використання *seconds* і *previous* для отримання історичних даних.

``` console
$ curl -sX GET http://localhost:8081/fledge/asset/sinusoid?seconds=5\&previous=60|jq
[
  { "reading": { "sinusoid": 1 }, "timestamp": "2022-11-09 09:37:51.930688" },
  { "reading": { "sinusoid": 0.994521895 }, "timestamp": "2022-11-09 09:37:50.930887" },
  { "reading": { "sinusoid": 0.978147601 }, "timestamp": "2022-11-09 09:37:49.933698" },
  { "reading": { "sinusoid": 0.951056516 }, "timestamp": "2022-11-09 09:37:48.930644" },
  { "reading": { "sinusoid": 0.913545458 }, "timestamp": "2022-11-09 09:37:47.930950" }
]

Наведений вище виклик повернув 5 секунд даних від поточного часу мінус 65 секунд до поточного часу мінус 5 секунд.

GET asset reading

GET /fledge/asset/{code}/{reading} - Повертає масив окремих зчитувзань для даного коду активу.

Параметри шляху

code - код активу для отримання.
reading - датчик із зчитування активів у форматі JSON.

Параметри запиту

limit - встановлює обмеження кількості показань для повернення. Якщо не вказано, за замовчуванням 20 одноразових показань.

skip - кількість активів, які потрібно пропустити. Це використовується разом з обмеженням і дозволяє абоненту не просто отримати останні N показників, але й отримати набір показників за минулі періоди.

seconds - це, по суті, альтернативна форма ліміту, але тут ліміт виражається у секундах, а не у кількості зчитувань. Вона поверне показники за останні N секунд. Зауважте, що його не можна використовувати разом з параметрами limit і skip або з параметрами запиту hours і minutes.

minutes - це, по суті, альтернативна форма ліміту, але тут ліміт виражається у хвилинах, а не у кількості зчитувань. Вона поверне показання за останні N хвилин. Зауважте, що його не можна використовувати разом з параметрами limit і skip або з параметрами запиту seconds і hours.

hours - це, по суті, альтернативна форма ліміту, але тут ліміт виражається в годинах, а не в кількості зчитувань. Вона поверне показники за останні N годин. Зауважте, що його не можна використовувати разом з параметрами limit і skip або з параметрами запиту seconds і minutes.

previous - Він використовується разом з параметром запиту hours, minutes або seconds і дозволяє користувачеві отримати не лише останні показники, але й історичні дані. Значення previous визначається в годинах, хвилинах або секундах, залежно від того, з яким параметром він використовується, і визначає, наскільки давно повинні закінчуватися дані, що повертаються. Якщо користувач передає набір параметрів seconds=30&previous=120, виклик поверне дані за 30 секунд, а найсвіжіші дані будуть 120-секундної давності.

Response Payload

Масив JSON-об'єктів з серією зчитувань, відсортованих у зворотному хронологічному порядку.

Назва	Тип	Опис	Приклад
timestamp	timestamp	Час, коли отримано зчитування	2023-04-14 12:04:34.603937
reading	JSON object	Значення зазначеного зчитування	`{"lux": 47705.68}`

Example

$ curl -sX GET http://localhost:8081/fledge/asset/asset_2/lux
[
  {"timestamp": "2023-04-14 12:04:34.603937", "lux": 47705.68},
  {"timestamp": "2023-04-14 12:02:39.150106", "lux": 97967.9},
  {"timestamp": "2023-04-14 12:02:26.616200", "lux": 28788.154},
  {"timestamp": "2023-04-14 12:02:11.171319", "lux": 57992.674},
  {"timestamp": "2023-04-14 12:01:56.979407", "lux": 10373.945}
]
$

$ curl -sX GET http://localhost:8081/fledge/asset/asset_2/lux?limit=3
[
  {"timestamp": "2023-04-14 11:25:05.672528", "lux": 75723.923},
  {"timestamp": "2023-04-14 11:24:49.767983", "lux": 50475.99},
  {"timestamp": "2023-04-14 11:23:15.672528", "lux": 75723.923}
]
.

#### GET asset reading summary

`GET /fledge/asset/{code}/{reading}/summary` - Повертає мінімальне,
максимальне та середнє значення зчитування за кодом активу.

**Параметри шляху**

-   **code** - код активу для отримання.
-   **reading** - датчик із зчитування активів у форматі JSON.

**Response Payload**

Об’єкт JSON зчитувань за кодом активу.

| Назва        | Тип    | Опис                                                                  | Приклад    |
|--------------|--------|-----------------------------------------------------------------------|------------|
| .lux.min     | number | Мінімальне значення набору значень датчика, вибраного в рядку запиту  | 10373.945  |
| .lux.max     | number | Максимальне значення набору значень датчика, вибраного в рядку запиту | 97967.9    |
| .lux.average | number | Середне значення набору значень датчика, вибраного в рядку запиту     | 48565.6706 |

**Example**

``` console
$ curl -sX GET http://localhost:8081/fledge/asset/asset_2/lux/summary
  {"lux": {"min": 10373.945, "max": 97967.9, "average": 48565.6706}}
.

#### GET all asset reading timespan

`GET /fledge/asset/timespan` - Повертає найновішу та найстарішу мітки
часу кожного активу, для якого ми зберігаємо зчитування в буфері.

**Response Payload**

Масив об’єктів JSON із найновішими та найстарішими мітками часу
зчитувань, які зберігаються для кожного активу.

| Назва      | Тип    | Опис                                                                | Приклад                    |
|------------|--------|---------------------------------------------------------------------|----------------------------|
| oldest     | string | Найстаріша позначка часу, що зберігається в буфері для цього активу | 2022-11-08 17:07:02.623258 |
| newest     | string | Найновіша позначка часу, що зберігається в буфері для цього активу  | 2022-11-09 14:52:50.069432 |
| asset_code | string | Код активу, для якого стосуються мітки часу                         | sinusoid                   |

**Example**

``` console
$ curl -sX GET http://localhost:8081/fledge/asset/timespan
[
  {
    "oldest": "2022-11-08 17:07:02.623258",
    "newest": "2022-11-09 14:52:50.069432",
    "asset_code": "sinusoid"
  }
]

GET asset reading timespan

GET /fledge/asset/{code}/timespan - Повертає найновішу та найстарішу позначки часу, для яких ми зберігаємо зчитування в буфері.

Параметри шляху

code - код активу для отримання.

Response Payload

Об’єкт JSON із найновішою та найстарішою мітками часу для активу, що зберігається в буфері зберігання.

Назва	Тип	Опис	Приклад
oldest	string	Найстаріша позначка часу, що зберігається в буфері для цього активу	2022-11-08 17:07:02.623258
newest	string	Найновіша позначка часу, що зберігається в буфері для цього активу	2022-11-09 14:52:50.069432

Example

$ curl -sX GET http://localhost:8081/fledge/asset/sinusoid/timespan|jq
  {
    "oldest": "2022-11-08 17:07:02.623258",
    "newest": "2022-11-09 14:59:14.069207"
  }

GET timed average asset reading

GET /fledge/asset/{code}/{reading}/series - Повертає мінімальне, максимальне та середнє значення зчитування за кодом активу в часовому ряді. За замовчуванням інтервал у ряді дорівнює одній секунді.

Параметри шляху

code - код активу для отримання.
reading - код активу для отримання.

Параметри запиту

limit - встановлює обмеження кількості зчитувань для повернення. Якщо не вказано, за замовчуванням 20 зчитувань.

skip - кількість активів, які потрібно пропустити. Це використовується в поєднанні з лімітом і дозволяє абоненту не просто отримати останні N зчитувань, але й отримати набір попередніх зчитувань.

seconds - це, по суті, альтернативна форма ліміту, але тут ліміт виражається у секундах, а не у кількості зчитувань. Вона поверне показники за останні N секунд. Зауважте, що його не можна використовувати разом з параметрами limit і skip або з параметрами запиту hours і minutes.

minutes - це, по суті, альтернативна форма ліміту, але тут ліміт виражається у хвилинах, а не у кількості зчитувань. Вона поверне показання за останні N хвилин. Зауважте, що його не можна використовувати разом з параметрами limit і skip або з параметрами запиту seconds і hours.

hours - це, по суті, альтернативна форма ліміту, але тут ліміт виражається в годинах, а не в кількості зчитувань. Вона поверне показники за останні N годин. Зауважте, що його не можна використовувати разом з параметрами limit і skip або з параметрами запиту seconds і minutes.

previous - Він використовується разом з параметром запиту hours, minutes або seconds і дозволяє користувачеві отримати не лише останні показники, але й історичні дані. Значення previous визначається в годинах, хвилинах або секундах, залежно від того, з яким параметром він використовується, і визначає, наскільки давно повинні закінчуватися дані, що повертаються. Якщо користувач передає набір параметрів seconds=30&previous=120, виклик поверне дані за 30 секунд, а найсвіжіші дані будуть 120-секундної давності.

Response Payload

Масив JSON-об'єктів з серією зчитувань, відсортованих у зворотному хронологічному порядку.

Назва	Тип	Опис	Приклад
min	number	Мінімальне значення набору значень датчика, вибраного в рядку запиту	47705.68
max	number	Максимальне значення набору значень датчика, вибраного в рядку запиту	47705.68
average	number	Середне значення набору значень датчика, вибраного в рядку запиту	47705.68
timestamp	timestamp	Час, який відображає зчитування	2023-04-14 12:04:34

Example

$ curl -sX GET http://localhost:8081/fledge/asset/asset_2/lux/series
[
  {"min": 47705.68, "max": 47705.68, "average": 47705.68, "timestamp": "2023-04-14 12:04:34"},
  {"min": 97967.9, "max": 97967.9, "average": 97967.9, "timestamp": "2023-04-14 12:02:39"},
  {"min": 28788.154, "max": 28788.154, "average": 28788.154, "timestamp": "2023-04-14 12:02:26"},
  {"min": 57992.674, "max": 57992.674, "average": 57992.674, "timestamp": "2023-04-14 12:02:11"},
  {"min": 10373.945, "max": 10373.945, "average": 10373.945, "timestamp": "2023-04-14 12:01:56"}
]
$

$ curl -sX GET http://localhost:8081/fledge/asset/asset_2/lux/series?limit=3
[
  {"min": 47705.68, "max": 47705.68, "average": 47705.68, "timestamp": "2023-04-14 12:04:34"},
  {"min": 97967.9, "max": 97967.9, "average": 97967.9, "timestamp": "2023-04-14 12:02:39"},
  {"min": 28788.154, "max": 28788.154, "average": 28788.154, "timestamp": "2023-04-14 12:02:26"}
]

Використання seconds і previous для отримання історичних даних.

$ curl -sX GET http://localhost:8081/fledge/asset/asset_2/lux/series?seconds=5\&previous=60
[
    {"min": 47705.68, "max": 47705.68, "average": 47705.68, "timestamp": "2023-04-14 12:04:34"}
]
.

Наведений вище виклик повернув 5 секунд даних від поточного часу мінус
65 секунд до поточного часу мінус 5 секунд.

Перегляд активів​

asset​

GET all assets​

GET asset reading​

GET asset reading timespan​

GET timed average asset reading​

Перегляд активів

asset

GET all assets

GET asset reading

GET asset reading timespan

GET timed average asset reading