Back to top

History

This service is intended to provide an easy way to consume data associated to device attributes, such as temperature readinds, and notifications sent by other services.

Note: The dates on this service use ISO 8601.

Retrieve data from attributes

This endpoint retrieves the last (or first) values associated to a device. The query string might select more than one attribute. For instance:

?lastN=3&attr=temperature,pressure will return the last 3 values from both temperature and pressure attributes.

?firstN=3&attr=temperature,pressure will return the first 3 values (the oldest ones) from both temperature and pressure attributes.

Note that when the firstN parameter is informed, the query returns the first records that were inserted in the database, that is, the oldest ones are returned first in the list. In this way, we have an ascending order in relation to the timestamp.
When the lastN parameter is informed, the query returns the last records that were inserted in the database, that is, the newest ones are returned first in the list. In this way, we have a descending order in relation to the timestamp.

If no query string is set, then all values from all attributes are returned.

Filter by last N values and only one attribute

Filter by last N values and only one attribute
GET/device/{device_id}/history?lastN={lastN}&attr={attr}&dateFrom={dateFrom}&dateTo={dateTo}

Example URI

GET http://localhost:8000/history/device/b374a5/history?lastN=3&attr=temperature&dateFrom=2018-06-05T18:00:00Z&dateTo=2018-06-15T18:00:00Z
URI Parameters
HideShow
device_id
string (required) Example: b374a5

Device identifier

attr
string (optional) Example: temperature

Device attribute to be requested. If not used, returns all attributes. (It can be a comma-separated list of attributes.)

dateFrom
string (optional) Example: 2018-06-05T18:00:00Z

Start time of a time-based query

dateTo
string (optional) Example: 2018-06-15T18:00:00Z

End time of a time-based query

lastN
number (optional) Example: 3

Number of most current values (valid for each attribute, if more than one). You can use lastN with or without dateFrom/dateTo.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer JWT
Response  200
HideShow
Headers
Content-Type: application/json; charset=UTF-8
Body
[
  {
    "device_id": "b374a5",
    "ts": "2018-02-14T13:43:33.306000Z",
    "metadata": {
      "protocol": "mqtt",
      "payload": "json"
    },
    "value": "22.12",
    "attr": "temperature"
  },
  {
    "device_id": "b374a5",
    "ts": "2018-02-14T13:42:33.306000Z",
    "metadata": {
      "protocol": "mqtt",
      "payload": "json"
    },
    "value": "23.12",
    "attr": "temperature"
  },
  {
    "device_id": "b374a5",
    "ts": "2018-02-14T13:41:33.306000Z",
    "metadata": {
      "protocol": "mqtt",
      "payload": "json"
    },
    "value": "24.10",
    "attr": "temperature"
  }
]
Response  404
HideShow

This does not mean that there is no such device in the dojot, just that there is no history for that device yet.

Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "title": "Device not found",
  "description": "No data for the given device could be found"
}
Response  404
HideShow

This does not mean that there is no such attribute on the device, only that there is no history for that attribute yet.

Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "title": "Attr not found",
  "description": "No data for the given attribute could be found"
}

Filter by first N values and somes attributes

Filter by first N values and somes attributes
GET/device/{device_id}/history?firstN={firstN}&attr={attr}&dateFrom={dateFrom}&dateTo={dateTo}

Example URI

GET http://localhost:8000/history/device/b374a5/history?firstN=3&attr=temperature,pressure&dateFrom=2010-01-01T00:00:00Z&dateTo=2018-06-15T18:00:00Z
URI Parameters
HideShow
device_id
string (required) Example: b374a5

Device identifier

attr
string (optional) Example: temperature,pressure

Device attribute to be requested. If not used, returns all attributes. (It can be a comma-separated list of attributes.)

dateFrom
string (optional) Example: 2010-01-01T00:00:00Z

Start time of a time-based query

dateTo
string (optional) Example: 2018-06-15T18:00:00Z

End time of a time-based query

firstN
number (optional) Example: 3

Number of oldest values (valid for each attribute, if more than one). You can use firstN with or without dateFrom/dateTo.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer JWT
Response  200
HideShow
Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "temperature": [
    {
      "device_id": "b374a5",
      "ts": "2010-01-01T10:11:22.306000Z",
      "metadata": {
        "protocol": "mqtt",
        "payload": "json"
      },
      "value": "24.10",
      "attr": "temperature"
    },
    {
      "device_id": "b374a5",
      "ts": "2010-01-01T10:12:22.306000Z",
      "metadata": {
        "protocol": "mqtt",
        "payload": "json"
      },
      "value": "23.12",
      "attr": "temperature"
    },
    {
      "device_id": "b374a5",
      "ts": "2010-01-01T10:13:22.306000Z",
      "metadata": {
        "protocol": "mqtt",
        "payload": "json"
      },
      "value": "22.12",
      "attr": "temperature"
    }
  ],
  "pressure": [
    {
      "device_id": "b374a5",
      "ts": "2010-01-01T10:11:22.306000Z",
      "metadata": {
        "protocol": "mqtt",
        "payload": "json"
      },
      "value": "1053",
      "attr": "pressure"
    },
    {
      "device_id": "b374a5",
      "ts": "2010-01-01T10:12:22.306000Z",
      "metadata": {
        "protocol": "mqtt",
        "payload": "json"
      },
      "value": "1033",
      "attr": "pressure"
    },
    {
      "device_id": "b374a5",
      "ts": "2010-01-01T10:13:22.306000Z",
      "metadata": {
        "protocol": "mqtt",
        "payload": "json"
      },
      "value": "1013",
      "attr": "pressure"
    }
  ]
}
Response  200
HideShow

If there is no data for the filter used.

Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "temperature": [],
  "pressure": []
}
Response  404
HideShow

This does not mean that there is no such device in the dojot, just that there is no history for that device yet.

Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "title": "Device not found",
  "description": "No data for the given device could be found"
}

Retrieving notifications

This endpoint retrieves the last 10 notifications generated by services. As each notification might have different attributes, it is possible to filter them and select only those needed by a particular application.

Get notifications from a tenant

Get notifications from a tenant
GET/notifications/history

Example URI

GET http://localhost:8000/history/notifications/history
Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer JWT
Response  200
HideShow
Headers
Content-Type: application/json; charset=UTF-8
Body
{
  "notifications": [
    {
      "msgID": "0caa7ff1-c6c2-4171-8a58-6f6cf8e137d8",
      "metaAttrsFilter": {
        "level": 3,
        "shouldPersist": true
      },
      "message": "Something went wrong.",
      "subject": "user_notification",
      "ts": "2019-02-20T17:17:52.863000Z"
    }
  ]
}

Generated by aglio on 11 May 2021