REST API

Endpoint Time Series service API documentation version v1

{schema}://{host}/api/{version}

  • schema: required (one of http, https - default: http)
  • host: required (string - default: localhost)
  • version: required (v1)

Time series

/time-series/config get

get /time-series/config

Returns configurations of all time series in application(s).

Secured by OAuth 2.0 with scopes:
  • application:timeseries-config:read

EPTS supports OAuth 2.0 for authenticating all API requests.

Query Parameters

  • applicationNames: (string)

    Zero or more application name(s). If not specified, data is returned for all available applications.

    Example:

    smart-house, smart-lamp

HTTP status code 200

Map of time series configurations by application name.

Body

Media type: application/json

Type: object

Example:

{
  "smart-house": [
    {
      "name": "temperature",
      "values": ["value"]
    },
    {
      "name": "humidity",
      "values": ["value"]
    }
  ],
  "smart-lamp": [
    {
      "name": "location",
      "values": ["lattitude", "longitude"]
    }
  ]
}

Secured by OAuth 2.0

Headers

  • Authorization: (string)

    Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

Time series data

/applications/{applicationName}/time-series/last get

get /applications/{applicationName}/time-series/last

Returns the most recent time series data.

Secured by OAuth 2.0 with scopes:
  • endpoint:read

EPTS supports OAuth 2.0 for authenticating all API requests.

URI Parameters

  • applicationName: required (string)

    Application name

    Example:

    0327fc40-7ac1-4ad0-8a5f-f352e69fcda7

Query Parameters

  • endpointId: (string)

    Zero or more endpoint ID(s). If not specified, data is returned for all available endpoints.

    Example:

    2ebaf0ab-76f3-4211-a27f-af310be8987f,8b4aec8a-0a13-4b92-ba0b-0a39cfd5e297
  • timeSeriesName: required (string)

    One or more time series name(s).

    Example:

    temperature,humidity
  • beforeDate: (datetime)

    ISO-8601 encoded time before which to retrieve data points.

    Example:

    2017-04-20T12:00:00.000Z

HTTP status code 200

Arrays of most recent data points mapped by time series names and endpoint IDs.

Body

Media type: application/json

Type: object

Example:

{
  "2ebaf0ab-76f3-4211-a27f-af310be8987f": {
    "temperature": [
      {
        "timestamp": "2017-04-20T11:19:57.848Z",
        "values": {
          "value": 20.2,
          "lat": 40.766892,
          "lon": -74.344482
        }
      }
    ],
    "humidity": [
      {
        "timestamp": "2017-04-20T11:19:57.848Z",
        "values": {
          "value": 63,
          "lat": 40.766892,
          "lon": -74.344482
        }
      }
    ]
  },
  "8b4aec8a-0a13-4b92-ba0b-0a39cfd5e297": {
    "temperature": [
      {
        "timestamp": "2017-04-20T11:19:57.848Z",
        "values": {
          "value": 23.1,
          "lat": 40.766892,
          "lon": -74.344482
        }
      }
    ],
    "humidity": [
      {
        "timestamp": "2017-04-20T11:19:57.848Z",
        "values": {
          "value": 75,
          "lat": 40.766892,
          "lon": -74.344482
        }
      }
    ]
  }
}

Secured by OAuth 2.0

Headers

  • Authorization: (string)

    Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

/applications/{applicationName}/time-series/data get put

get /applications/{applicationName}/time-series/data

Returns historical time series data within the specified time range.

Secured by OAuth 2.0 with scopes:
  • endpoint:read

EPTS supports OAuth 2.0 for authenticating all API requests.

URI Parameters

  • applicationName: required (string)

    Application name

    Example:

    0327fc40-7ac1-4ad0-8a5f-f352e69fcda7

Query Parameters

  • timeSeriesName: required (string)

    One or more time series names.

    Example:

    temperature,humidity
  • endpointId: (string)

    Zero or more endpoint IDs. If not specified, data is returned for all available endpoints.

    Example:

    2ebaf0ab-76f3-4211-a27f-af310be8987f,8b4aec8a-0a13-4b92-ba0b-0a39cfd5e297
  • fromDate: required (datetime)

    ISO-8601 encoded start time to retrieve data points from.

    Example:

    2017-04-20T00:00:00.000Z
  • toDate: required (datetime)

    ISO 8601 encoded end time to retrieve data points to.

    Example:

    2017-04-22T00:00:00.000Z
  • includeTime: (one of from, to, both, none - default: none)

    Defines which of the fromDate and toDate are inclusive.

  • sort: (one of ASC, DESC - default: ASC)

    Sorting order by timestamp.

HTTP status code 200

Array of objects, each contains arrays of most recent data points mapped by time series names and endpoint IDs. The response is returned in chunks. Each chunk is guaranteed to contain an integer number of top-level array elements. The same endpoint ID (and time series name) may occur in several chunks (note an example of that below).

Body

Media type: application/json

Type: array of object

Example:

[
  {
    "2ebaf0ab-76f3-4211-a27f-af310be8987f":{
      "temperature":[
        {
          "timestamp":"2017-04-20T11:19:57.848Z",
          "values":{
            "value":20.2,
            "lat":40.766892,
            "lon":-74.344482
          }
        },
        {
          "timestamp":"2017-04-20T11:20:57.848Z",
          "values":{
            "value":20.7,
            "lat":40.766892,
            "lon":-74.344482
          }
        }
      ],
      "humidity":[
        {
          "timestamp":"2017-04-20T11:19:57.848Z",
          "values":{
            "value":63,
            "lat":40.766892,
            "lon":-74.344482
          }
        }
      ]
    }
  },
  {
    "2ebaf0ab-76f3-4211-a27f-af310be8987f":{
      "temperature":[
        {
          "timestamp":"2017-04-20T11:21:57.848Z",
          "values":{
            "value":20.9,
            "lat":40.766892,
            "lon":-74.344482
          }
        }
      ]
    },
    "8b4aec8a-0a13-4b92-ba0b-0a39cfd5e297":{
      "temperature":[
        {
          "timestamp":"2017-04-20T11:19:57.848Z",
          "values":{
            "value":23.1,
            "lat":40.766892,
            "lon":-74.344482
          }
        },
        {
          "timestamp":"2017-04-20T11:20:57.848Z",
          "values":{
            "value":22.8,
            "lat":40.766892,
            "lon":-74.344482
          }
        }
      ],
      "humidity":[
        {
          "timestamp":"2017-04-20T11:19:57.848Z",
          "values":{
            "value":75,
            "lat":40.766892,
            "lon":-74.344482
          }
        }
      ]
    }
  }
]

Secured by OAuth 2.0

Headers

  • Authorization: (string)

    Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

put /applications/{applicationName}/time-series/data

Updates time series data for the specified endpoints.

Time series data structure must match the configured time series definition (explicit JSON null values are permitted for any data point value). Data points with the same timestamp are re-writen on subsequent updates.

Unlike with time series data received from DSTP and TSTP interfaces, the data submitted using this API is not sent to the TSTP interface.

Secured by OAuth 2.0 with scopes:
  • endpoint:update

EPTS supports OAuth 2.0 for authenticating all API requests.

URI Parameters

  • applicationName: required (string)

    Application name

    Example:

    0327fc40-7ac1-4ad0-8a5f-f352e69fcda7

Annotations

  • deprecated:
    {"since":"v1.2.0","replaceWith":"PUT: /app-versions/{appVersionName}/time-series/data"}

Body

Media type: application/json

Type: Map of endpoint IDs to their time series. Each time series represented as a map of time series name to the array of data poins. A data point is a data structure consisting of a `timestamp` and one or more named `values`. The `timestamp` is in ISO 8601 format (UTC timezone). Data point values can be of an arbitrary primitive or a composite data type.

Example:

{
  "2ebaf0ab-76f3-4211-a27f-af310be8987f": {
    "temperature": [
      {
        "timestamp": "2017-04-20T11:19:57.848Z",
        "values": {
          "value": 20.2,
          "lat": 40.766892,
          "lon": -74.344482
        }
      },
      {
        "timestamp": "2017-04-20T11:20:57.848Z",
        "values": {
          "value": 20.7,
          "lat": 40.766892,
          "lon": -74.344482
        }
      }
    ],
    "humidity": [
      {
        "timestamp": "2017-04-20T11:19:57.848Z",
        "values": {
          "value": 63,
          "lat": 40.766892,
          "lon": -74.344482
        }
      }
    ]
  },
  "8b4aec8a-0a13-4b92-ba0b-0a39cfd5e297": {
    "temperature": [
      {
        "timestamp": "2017-04-20T11:19:57.848Z",
        "values": {
          "value": 23.1,
          "lat": 40.766892,
          "lon": -74.344482
        }
      },
      {
        "timestamp": "2017-04-20T11:20:57.848Z",
        "values": {
          "value": 22.8,
          "lat": 40.766892,
          "lon": -74.344482
        }
      }
    ],
    "humidity": [
      {
        "timestamp": "2017-04-20T11:19:57.848Z",
        "values": {
          "value": 75,
          "lat": 40.766892,
          "lon": -74.344482
        }
      }
    ]
  }
}

HTTP status code 204

Endpoints time series data successfully updated.

HTTP status code 400

Request is not valid (payload is not a JSON object, time series name is not valid, content does not match the time series definition, etc).

HTTP status code 404

Some of the requested endpoints are not found or the querying user is denied access.

Secured by OAuth 2.0

Headers

  • Authorization: (string)

    Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

Time series data by application version

/app-versions/{appVersionName}/time-series/data put

put /app-versions/{appVersionName}/time-series/data

Updates time series data for the specified endpoints.

Time series data structure must match the configured time series definition (explicit JSON null values are permitted for any data point value). Data points with the same timestamp are re-writen on subsequent updates.

Secured by OAuth 2.0 with scopes:
  • endpoint:update

EPTS supports OAuth 2.0 for authenticating all API requests.

URI Parameters

  • appVersionName: required (string)

    Application version name

    Example:

    0327fc40-7ac1-4ad0-8a5f-f352e69fcda7-v1

Body

Media type: application/json

Type: Map of endpoint IDs to their time series. Each time series represented as a map of time series name to the array of data poins. A data point is a data structure consisting of a `timestamp` and one or more named `values`. The `timestamp` is in ISO 8601 format (UTC timezone). Data point values can be of an arbitrary primitive or a composite data type.

Example:

{
  "2ebaf0ab-76f3-4211-a27f-af310be8987f": {
    "temperature": [
      {
        "timestamp": "2017-04-20T11:19:57.848Z",
        "values": {
          "value": 20.2,
          "lat": 40.766892,
          "lon": -74.344482
        }
      },
      {
        "timestamp": "2017-04-20T11:20:57.848Z",
        "values": {
          "value": 20.7,
          "lat": 40.766892,
          "lon": -74.344482
        }
      }
    ],
    "humidity": [
      {
        "timestamp": "2017-04-20T11:19:57.848Z",
        "values": {
          "value": 63,
          "lat": 40.766892,
          "lon": -74.344482
        }
      }
    ]
  },
  "8b4aec8a-0a13-4b92-ba0b-0a39cfd5e297": {
    "temperature": [
      {
        "timestamp": "2017-04-20T11:19:57.848Z",
        "values": {
          "value": 23.1,
          "lat": 40.766892,
          "lon": -74.344482
        }
      },
      {
        "timestamp": "2017-04-20T11:20:57.848Z",
        "values": {
          "value": 22.8,
          "lat": 40.766892,
          "lon": -74.344482
        }
      }
    ],
    "humidity": [
      {
        "timestamp": "2017-04-20T11:19:57.848Z",
        "values": {
          "value": 75,
          "lat": 40.766892,
          "lon": -74.344482
        }
      }
    ]
  }
}

HTTP status code 204

Endpoints time series data successfully updated.

HTTP status code 400

Request is not valid (payload is not a JSON object, time series name is not valid, content does not match the time series definition, etc).

HTTP status code 404

Some of the requested endpoints are not found or the querying user is denied access.

Secured by OAuth 2.0

Headers

  • Authorization: (string)

    Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.