User API Reference

The user API provides a mechanism to access the data that is buffered within FogLAMP. It is designed to allow users and applications to get a view of the data that is available in the buffer and do analysis and possibly trigger actions based on recently received sensor readings.

In order to use the entry points in the user API, with the exception of the /foglamp/authenticate entry point, there must be an authenticated client calling the API. The client must provide a header field in each request, authtoken, the value of which is the token that was retrieved via a call to /foglamp/authenticate. This token must be checked for validity and also that the authenticated entity has user or admin permissions.

Browsing Assets

asset

The asset method is used to browse all or some assets, based on search and filtering.

GET all assets

GET /foglamp/asset - Return an array of asset codes buffered in FogLAMP and a count of assets by code.

Response Payload

An array of JSON objects, one per asset.

Name

Type

Description

Example

count

number

The number of recorded readings for the asset code

11

assetCode

string

The code of the asset

asset_1

Example

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

GET asset readings

GET /foglamp/asset/{code} - Return an array of readings for a given asset code.

Path Parameters

  • code - the asset code to retrieve.

Request Parameters

  • limit - set the limit of the number of readings to return. If not specified, the defaults is 20 readings.

  • skip - the number of assets to skip. This is used in conjunction with limit and allows the caller to not just get the last N readings, but to get a set of readings from the past.

  • seconds - this is essentially an alternative form of limit, but here the limit is expressed in seconds rather than a number of readings. It will return the readings for the last N seconds. Note that this can not be used in conjunction with the limit and skip or with hours and minutes request parameters.

  • minutes - this is essentially an alternative form of limit, but here the limit is expressed in minutes rather than a number of readings. It will return the readings for the last N minutes. Note that this can not be used in conjunction with the limit and skip or with seconds and hours request parameters.

  • hours - this is essentially an alternative form of limit, but here the limit is expressed in hours rather than a number of readings. It will return the readings for the last N hours. Note that this can not be used in conjunction with the limit and skip or with seconds and minutes request parameters.

  • previous - This is used in conjunction with the hours, minutes or seconds request parameter and allows the caller to get not just the most recent readings but historical readings. The value of previous is defined in hours, minutes or seconds dependent upon the parameter it is used with and defines how long ago the data that is returned should end. If the caller passes a set of parameters seconds=30&previous=120 the call will return 30 seconds worth of data and the newest data returned will be 120 seconds old.

Response Payload

An array of JSON objects with the readings data for a series of readings sorted in reverse chronological order.

Name

Type

Description

Example

reading

JSON object

The JSON reading object received from the sensor

{“pressure”: 885.7}

timestamp

timestamp

The time at which the reading was received

2023-04-14 12:04:34.603963

Example

$ curl -sX GET http://localhost:8081/foglamp/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/foglamp/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"}
]
$

Using seconds and previous to obtain historical data.

$ curl -sX GET http://localhost:8081/foglamp/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" }
]

The above call returned 5 seconds of data from the current time minus 65 seconds to the current time minus 5 seconds.

GET asset reading

GET /foglamp/asset/{code}/{reading} - Return an array of single readings for a given asset code.

Path Parameters

  • code - the asset code to retrieve.

  • reading - the sensor from the assets JSON formatted reading.

Request Parameters

  • limit - set the limit of the number of readings to return. If not specified, the defaults is 20 single readings.

  • skip - the number of assets to skip. This is used in conjunction with limit and allows the caller to not just get the last N readings, but to get a set of readings from the past.

  • seconds - this is essentially an alternative form of limit, but here the limit is expressed in seconds rather than a number of readings. It will return the readings for the last N seconds. Note that this can not be used in conjunction with the limit and skip or with hours and minutes request parameters.

  • minutes - this is essentially an alternative form of limit, but here the limit is expressed in minutes rather than a number of readings. It will return the readings for the last N minutes. Note that this can not be used in conjunction with the limit and skip or with seconds and hours request parameters.

  • hours - this is essentially an alternative form of limit, but here the limit is expressed in hours rather than a number of readings. It will return the readings for the last N hours. Note that this can not be used in conjunction with the limit and skip or with seconds and minutes request parameters.

  • previous - This is used in conjunction with the hours, minutes or seconds request parameter and allows the caller to get not just the most recent readings but historical readings. The value of previous is defined in hours, minutes or seconds dependent upon the parameter it is used with and defines how long ago the data that is returned should end. If the caller passes a set of parameters seconds=30&previous=120 the call will return 30 seconds worth of data and the newest data returned will be 120 seconds old.

Response Payload

An array of JSON objects with a series of readings sorted in reverse chronological order.

Name

Type

Description

Example

timestamp

timestamp

The time at which the reading was received

2023-04-14 12:04:34.603937

reading

JSON object

The value of the specified reading

{“lux”: 47705.68}

Example

$ curl -sX GET http://localhost:8081/foglamp/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/foglamp/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 /foglamp/asset/{code}/{reading}/summary - Return minimum, maximum and average values of a reading by asset code.

Path Parameters

  • code - the asset code to retrieve.

  • reading - the sensor from the assets JSON formatted reading.

Response Payload

A JSON object of a reading by asset code.

Name

Type

Description

Example

.lux.min

number

The minimum value of the set of sensor values selected in the query string

10373.945

.lux.max

number

The maximum value of the set of sensor values selected in the query string

97967.9

.lux.average

number

The average value of the set of sensor values selected in the query string

48565.6706

Example

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

GET all asset reading timespan

GET /foglamp/asset/timespan - Return newest and oldest timestamp of each asset for which we hold readings in the buffer.

Response Payload

An array of JSON objects with newest and oldest timestamps of the readings held for each asset.

Name

Type

Description

Example

oldest

string

The oldest timestamp held in the buffer for this asset

2022-11-08 17:07:02.623258

newest

string

The newest timestamp held in the buffer for this asset

2022-11-09 14:52:50.069432

asset_code

string

The asset code for which the timestamps refer

sinusoid

Example

$ curl -sX GET http://localhost:8081/foglamp/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 /foglamp/asset/{code}/timespan - Return newest and oldest timestamp for which we hold readings in the buffer.

Path Parameters

  • code - the asset code to retrieve.

Response Payload

A JSON object with the newest and oldest timestamps for the asset held in the storage buffer.

Name

Type

Description

Example

oldest

string

The oldest timestamp held in the buffer for this asset

2022-11-08 17:07:02.623258

newest

string

The newest timestamp held in the buffer for this asset

2022-11-09 14:52:50.069432

Example

$ curl -sX GET http://localhost:8081/foglamp/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 /foglamp/asset/{code}/{reading}/series - Return minimum, maximum and average values of a reading by asset code in a time series. The default interval in the series is one second.

Path Parameters

  • code - the asset code to retrieve.

  • reading - the sensor from the assets JSON formatted reading.

Request Parameters

  • limit - set the limit of the number of readings to return. If not specified, the defaults is 20 readings.

  • skip - the number of assets to skip. This is used in conjunction with limit and allows the caller to not just get the last N readings, but to get a set of readings from the past.

  • seconds - this is essentially an alternative form of limit, but here the limit is expressed in seconds rather than a number of readings. It will return the readings for the last N seconds. Note that this can not be used in conjunction with the limit and skip or with hours and minutes request parameters.

  • minutes - this is essentially an alternative form of limit, but here the limit is expressed in minutes rather than a number of readings. It will return the readings for the last N minutes. Note that this can not be used in conjunction with the limit and skip or with seconds and hours request parameters.

  • hours - this is essentially an alternative form of limit, but here the limit is expressed in hours rather than a number of readings. It will return the readings for the last N hours. Note that this can not be used in conjunction with the limit and skip or with seconds and minutes request parameters.

  • previous - This is used in conjunction with the hours, minutes or seconds request parameter and allows the caller to get not just the most recent readings but historical readings. The value of previous is defined in hours, minutes or seconds dependent upon the parameter it is used with and defines how long ago the data that is returned should end. If the caller passes a set of parameters seconds=30&previous=120 the call will return 30 seconds worth of data and the newest data returned will be 120 seconds old.

Response Payload

An array of JSON objects with a series of readings sorted in reverse chronological order.

Name

Type

Description

Example

min

number

The minimum value of the set of sensor values selected in the query string

47705.68

max

number

The maximum value of the set of sensor values selected in the query string

47705.68

average

number

The average value of the set of sensor values selected in the query string

47705.68

timestamp

timestamp

The time the reading represents

2023-04-14 12:04:34

Example

$ curl -sX GET http://localhost:8081/foglamp/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/foglamp/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"}
]

Using seconds and previous to obtain historical data.

  $ curl -sX GET http://localhost:8081/foglamp/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"}
  ]
$

The above call returned 5 seconds of data from the current time minus 65 seconds to the current time minus 5 seconds.