Data APIs

📝	The data processing pipeline may generate additional values for the hot path, warm path, and cold path storage. The values can be recognized by an identical timestamp. This behavior may have existed in prior versions but is mostly seen in the current version with the enhancements in the processing pipeline. See Known Issues for additional information.
☝️	The user applications must ensure that they apply a filter before processing the data in the application. There is no workaround when aggregates are processed. For example, if aggregates count, sum, or avg are measured, the duplicate values will be included in the results.

Payload

All of the endpoints below accept payload with the following parameters:

Parameter	Mandatory	Description	Data Type
date	yes	date object	JObject
date.from	yes	starting date range for query	string (ISO 8601 format)
date.to	no	ending date range for query; if not provided, will default to API server's current UTC time	string (ISO 8601 format)
filter	no	a predicate string adhering to ABB's Query Expression Language format	string
select	no	select object	JObject
select.properties	no	a comma-separated list of properties that will return in the response; if this field is set, then the items in this property's value will be the only properties in the response. Example: "properties": "objectId,model"	string
select.count	no	Count of results based upon the current filter. Requires an empty string value (ie: "count": "").	int
select.min	no	minimum value, only applicable to numeric and date time properties; supports multiple comma-separated list of property names. Example: value,timestamp.	string
select.max	no	maximum value, only applicable to numeric and date time properties. Supports multiple comma-separated list of property names. Example: value,timestamp.	string
select.first	no	First value, only applicable to numeric and date time properties. Supports multiple comma-separated list of property names. Example: timestamp or value.	string
select.last	no	last value; supports multiple comma-separated list of property names. Example: value,timestamp. Using timestamp will provide the exact timestamp of the value's occurrence. Therefore, using timestamp with last provides a true last known value searching capability.	string
select.sum	no	sum value, only applicable to numeric properties; supports multiple comma-separated list of property names.	string
select.avg	no	average value, only applicable to numeric properties; supports multiple comma-separated list of property names.	string
groupBy	no	object used to group the data	JObject
groupBy.time	no	used to group by a user-specified time interval; supported time intervals are m, h, d. Example: 1m, 10h, 5d. By specifying this property, timestamp will automatically be returned in the response. The timestamp value will be the histogram timestamp nearest the specified time interval, not the precise timestamp of the occurring value.	JObject
groupBy.properties	no	Group by values of specified properties, supports comma-separated list of property names. All properties for a given event type are supported.	JObject
orderBy	no	object used to order the data	JObject
orderBy.property	yes	property in which to order	string
orderBy.order	yes	order by property; available options are "asc" or "desc"	string
limit	no	post processing limit; example: If the warm data storage returns 10,000 records but this property is set to 100, then the top 100 records of that 10,000 will be returned.	int

POST Query Variables

/data/variables

Description

Properties in the response:
- objectId: string
- model: string
- variable: string
- quality: number
- timestamp: dateTime
- value: any primitive type

Examples

Have a look at some examples here

Responses

Code	Description	Schema
200	Success	Variables
400	Invalid request. Response will contain details about all encountered validation errors - i.e. request payload too large, malformed JSON, etc	ServiceErrors
401	Not Authorized. Either the Access token is missing or the access token validation failed
403	Access Forbidden. Requesting entity does not have enough permissions to access the resource
429	Too many requests - indicates the user has sent too many requests in a given amount of time	ServiceErrors
500	Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors	ServiceErrors

400

will be returned when the request object is invalid.

{
  "error": [
    {
      "code": "<integer>",
      "title": "<string>",
      "detail": "<string>"
    }
  ]
}

500

will be returned when there is an error processing the request.

{
  "error": [
    {
      "code": "<integer>",
      "title": "<string>",
      "detail": "<string>"
    }
  ]
}

Known Data Formatting Limitation

Data sent through Time Series Insights(TSI) cannot be modified by the user. If the data being sent through the TSI service accessed by the /data/variables endpoint is improperly formatted when sent from the device, then any queries made to this endpoint will return an HTTP 500 error. There is currently no automatic schema validation, so if a user begins to see consistent 500 errors it is suggested to validate the data is properly formatted based on the approved schema for variables. If the data is improperly formatted, the user will be required to purge all data from the service to recover.

Integer Data type round-off error

TSI supports Bool, DateTime, Double and String data types.

TSI does not distinguish between Integer and Double data types.

If type-definition is created as an Integer, this might lead to rounding errors. If this type-definition data is for more precision data, then create Double type instead of Integer data type.

POST Query Alarms

/data/alarms

Description

Properties in the response:
- objectId: string
- model: string
- alarm: string
- quality: number
- timestamp: dateTime
- value: object

Note that filtering is possible only on properties of primitive types (via the dot notation, i.e. value.foo.bar).

Responses

Code	Description	Schema
200	Success	Alarms
400	Invalid request. Response will contain details about all encountered validation errors - i.e. request payload too large, malformed JSON, etc	ServiceErrors
401	Not Authorized. Either the Access token is missing or the access token validation failed
403	Access Forbidden. Requesting entity does not have enough permissions to access the resource
429	Too many requests - indicates the user has sent too many requests in a given amount of time	ServiceErrors
500	Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors	ServiceErrors

400

will be returned when the request object is invalid.

{
  "error": [
    {
      "code": "<integer>",
      "title": "<string>",
      "detail": "<string>"
    }
  ]
}

500

will be returned when there is an error processing the request.

{
  "error": [
    {
      "code": "<integer>",
      "title": "<string>",
      "detail": "<string>"
    }
  ]
}

POST Query Events

/data/events

Description

Properties in the response:
- objectId: string
- model: string
- event: string
- quality: number
- timestamp: dateTime
- value: object

Note that filtering is possible only on properties of primitive types (via the dot notation, i.e. value.foo.bar).

Responses

Code	Description	Schema
200	Success	Events
400	Invalid request. Response will contain details about all encountered validation errors - i.e. request payload too large, malformed JSON, etc	ServiceErrors
401	Not Authorized. Either the Access token is missing or the access token validation failed
403	Access Forbidden. Requesting entity does not have enough permissions to access the resource
429	Too many requests - indicates the user has sent too many requests in a given amount of time	ServiceErrors
500	Service error. Service has encountered one or more unexpected conditions that prevented it from fulfilling the request, which may or may not be temporary. Response will contain more details about these errors	ServiceErrors

400

will be returned when the request object is invalid.

{
  "error": [
    {
      "code": "<integer>",
      "title": "<string>",
      "detail": "<string>"
    }
  ]
}

500

will be returned when there is an error processing the request.

{
  "error": [
    {
      "code": "<integer>",
      "title": "<string>",
      "detail": "<string>"
    }
  ]
}

Code 600 Exceptions

Use Case​​​

The data access API may throw a 600-exception error (FailureInCommandingService) when sending a request to the Ability Platform. In this scenario, a method invocation from the data access API is unable to reach the Edge proxy, which behaves as if it is disconnected. The root cause is broken connectivity between the cloud and directly connected devices or a non-operational Edge.

Error​​​

The resulting error message appears as follows:

{
    "errors": [
        {
            "code": "600",
            "title": "Device not found",
            "detail": "Reference Id 738f3e6a-48db00cf25576943 Device not found for objectId objectId_of_target_model_instance"​
        }
    ]
}

Typical Examples​​​

The following conditions may provoke the error:

• Edge-proxy container is down
• no network connection on the Edge level
• BL module is down
• no module response to the Edge proxy
• timeout on communication back to the Edge-proxy
• communication queue for C2D messages is full
• adding a parent to an Edge device that already contains a parent

Suggested Remedy​

The local application must be constructed in a way to handle 600 exception errors. Specifically, your software solution should be designed to deal with the conditions listed as typical examples (above), to include appropriate retry logic when cloud-to-device (C2D) communication is down. Users are also advised to include an Edge log for analysis.​