swagger: '2.0'
info:
title: IoT Time Series API
description:
Create, update, and query time series data with a precision of 1 millisecond.
version: "3.4.1"
x-visibility: "external"
schemes:
- https
basePath: /api/iottimeseries/v3
produces:
- application/json
securityDefinitions:
timeseries:
type: oauth2
flow: accessCode
authorizationUrl: 'https://oauth.simple.api/authorization'
tokenUrl: 'https://oauth.simple.api/token'
scopes:
iot.tim.r: read timeseries
iot.tim.w: write timeseries
iot.tim.d: delete timeseries
paths:
/timeseries:
put:
summary: Create or update time series data for mutiple unique asset-aspect (entity-property set) combinations.
tags:
- Time Series Operations
description: |
Create or update time series data for multiple unique combinations of assets (entities) and aspects (property sets).
In case of an update of data at an already existing time, all properties at that time will be replaced by the ones provided in the request. All asset-aspect (entity-property set) combinations need to belong to the same tenant.
Request body limitations:
1. A maximum of 5 asset-aspect (entity-property set) combinations can be provided
2. The request body size must be equal or less than 100 kb
3. A maximum of 100 time series data items can be provided overall
operationId: createOrUpdateTimeseries
security:
- timeseries:
- iot.tim.w
parameters:
- name: timeseries
in: body
required: true
schema:
$ref: '#/definitions/TimeSeries'
responses:
'202':
description: |
Accepted. For each asset-aspect (entity-property set) pair a validation error can occur. In case an error is returned for an asset-aspect (entity-property set) pair, time series data for that pair is not considered. Possible validation errors are
- 400: bad request schema for asset-aspect (entity-property set) pair
- 404: asset (entity) and/or aspect(proprety set) not found
- 429: asset-aspect (entity-property set) pair could not be processed due to too many requests
- default: unexpected error while processing
schema:
$ref: '#/definitions/MultiStatusError'
'400':
description: |
Bad request, in case the resource is invalid.
Few of the validations as below -
- Total number of records for all assets (entites) and aspects (property sets) should not be more than 100 per PUT request.
- Total size of the payload should not be more than 100 kb per PUT request.
- Payload cannot have more than 5 asset (entity)/aspect (property set) combinations.
schema:
$ref: '#/definitions/MultiTimeseiresBadRequest'
'401':
description: unauthorized
schema:
$ref: '#/definitions/Unauthorized'
'default':
description: Other error with any status code and response body format.
/timeseries/{entityId}/{propertySetName}:
parameters:
- name: entityId
in: path
description: unique identifier of the asset (entity)
required: true
type: string
minLength: 32
maxLength: 32
pattern: "[a-f0-9]{32}"
- name: propertySetName
in: path
description: Name of the aspect (property set).
required: true
type: string
get:
summary: Retrieve time series data
tags:
- Time Series Operations
description: |
Retrieve time series data for one combination of an asset (entity) and an(a) aspect (property set). The maximum number of time series data items returned per request is defined by parameter limit. In case more time series data items are present in the requested time range, only a subset of data items will be returned and a header link is added to the response. The header value contains the request URL to fetch the next set of time series data items, by increasing the from parameter accordingly. Returns the latest record if no range is provided.
operationId: retrieveTimeseries
security:
- timeseries:
- iot.tim.r
parameters:
- name: from
in: query
description: Beginning of the time range to be retrieved (exclusive).
required: false
type: string
format: date-time
- name: to
in: query
description: End of the time range to be retrieved (inclusive).
required: false
type: string
format: date-time
- name: limit
in: query
description: Maximum number of time series data items to be retrieved.
required: false
type: integer
default: 2000
maximum: 2000
- name: select
in: query
description: Comma-separated list of properties to be returned. By default all properties of an(a) aspect (property set) are considered.
required: false
type: string
- name: sort
in: query
description: Define sorting order of returned data. Sorting can be chronologically ascending (asc) or descending (desc).
required: false
type: string
enum: [asc, desc]
default: asc
- name: latestValue
in: query
description: If true, only the latest value of each property is returned. Latest values must be at least two hours old and at maximum 30 days old, in order to be considered. The returned values might be co-located or spread over multiple timestamps. Each property appears at max once in the response. The select parameter can be used to limit the properties to be considered. Parameters from, to, and limit must not be used in conjunction with latest.
required: false
type: boolean
default: false
responses:
'200':
description: array of time series
headers:
link:
type: string
description: Contains a link to the next page, if there is a next page
schema:
type: array
items:
$ref: '#/definitions/TimeSeriesDataItem'
'400':
description: bad request
schema:
$ref: '#/definitions/BadRequest'
'401':
description: unauthorized
schema:
$ref: '#/definitions/Unauthorized'
'404':
description: asset (entity) not found
schema:
$ref: '#/definitions/NotFound'
'default':
description: Other error with any status code and response body format.
put:
summary: Create or update time series data
tags:
- Time Series Operations
description: |
Create or update time series data for one combination of an asset (entity) and an(a) aspect (property set). In case of an update of data at an already existing time, all properties at that time will be replaced by the ones provided in the request.
operationId: createOrUpdateTimeseriesData
security:
- timeseries:
- iot.tim.w
parameters:
- name: timeseries
in: body
description: time series data array
required: true
schema:
type: array
items:
$ref: '#/definitions/TimeSeriesDataItem'
responses:
'204':
description: timeseries written
'400':
description: bad request
schema:
$ref: '#/definitions/BadRequest'
'401':
description: unauthorized
schema:
$ref: '#/definitions/Unauthorized'
'404':
description: asset (entity) not found
schema:
$ref: '#/definitions/NotFound'
'429':
description: too many requests
schema:
$ref: '#/definitions/TooManyRequests'
'default':
description: Other error with any status code and response body format.
delete:
summary: Delete time series data
tags:
- Time Series Operations
description: |
Delete time series data for one combination of an asset (entity) and an(a) aspect (property set). All property values within the given time range are deleted.
operationId: deleteTimeseries
security:
- timeseries:
- iot.tim.d
parameters:
- name: from
in: query
description: beginning of the timerange to delete (exclusive)
required: true
type: string
format: date-time
- name: to
in: query
description: end of the timerange to delete (inclusive)
required: true
type: string
format: date-time
responses:
'204':
description: deleted
'400':
description: bad request
schema:
$ref: '#/definitions/BadRequest'
'401':
description: unauthorized
schema:
$ref: '#/definitions/Unauthorized'
'404':
description: asset (entity) not found
schema:
$ref: '#/definitions/NotFound'
'default':
description: Other error with any status code and response body format.
x-ErrorTemplate: &ErrorTemplate
type: object
properties:
timestamp:
type: string
format: date-time
status:
type: number
error:
type: string
exception:
type: string
message:
type: string
path:
type: string
definitions:
TimeSeriesDataItem:
type: object
required: [_time]
properties:
_time:
type: string
description: Timestamp of the data points.
format: date-time
additionalProperties:
description: Properties as defined by the aspect (property set) containing the time series data.
example:
_time: "2019-02-10T23:01:00Z"
exampleproperty0: examplepropertyValue
exampleproperty0_qc: exampleproperty0_qc_Value
exampleproperty1: exampleproperty1Value
TimeSeriesItem:
type: object
required: [entityId,propertySetName,data]
properties:
entityId:
type: string
description: asset (entity) Id of timeseries data.
propertySetName:
type: string
description: aspect (property set) name of timeseries data.
data:
type: array
description: Timeseries data for corresponsding asset (entity) Id and aspect (property set) name.
items:
$ref: '#/definitions/TimeSeriesDataItem'
TimeSeries:
description: Time series of a set of asset-aspect (entity-property set) combinations.
type: object
properties:
timeseries:
type: array
items:
$ref: '#/definitions/TimeSeriesItem'
example:
- entityId: entityId1
propertySetName: propertySetName1
data:
- _time: "2019-02-10T23:00:00Z"
rpm: rpmValue1
rpm_qc: rpm_qcValue1
enginetemperature: enginetemperatureValue1
- time: "2019-02-10T23:01:00Z"
rpm: rpmValue2
rpm_qc: rpm_qcValue2
enginetemperature: enginetemperatureValue2
- entityId: entityId2
propertySetName: propertySetName2
data:
- _time: "2019-02-10T23:00:00Z"
height: heightValue
height_qc: height_qcValue
carmanual: carmanualValue
- entityId: entityId3
propertySetName: propertySetName3
data:
- _time: "2019-02-10T23:00:00Z"
speed: speedValue
speed_qc: speed_qcValue
width: widthValue
MultiStatusError:
description: a (errors, errorObject).
type: object
properties:
errors:
type: array
items:
$ref: '#/definitions/MultiStatusErrorItem'
MultiStatusErrorItem:
type: object
properties:
timestamp:
type: string
format: date-time
example: 2019-04-08T06:32:01.261+0000
status:
type: number
example: 404
error:
type: string
example: 'Not Found'
exception:
type: string
example: 'com.siemens.mindsphere.iot.exception.IotException'
message:
type: string
example: '[6007] Invalid value '' for request param - propertysetname'
entityId:
type: string
example: 'entityId2'
propertySetName:
type: string
example: 'propertySetName2'
path:
type: string
example: '/api/iottimeseries/v3/timeseries'
BadRequest:
<<: *ErrorTemplate
example:
timestamp: "2019-04-08T06:32:01.261+0000"
status: 400
error: "Bad Request"
exception: "com.siemens.mindsphere.iot.exception.IotException"
message: "[6008] Invalid date format '2018-10-16T00:00:00Z111' for request param - from"
path: "/api/iottimeseries/v3/timeseries/entityId/propertySetName"
MultiTimeseiresBadRequest:
<<: *ErrorTemplate
example:
timestamp: "2019-04-08T06:32:01.261+0000"
status: 400
error: "Bad Request"
exception: "com.siemens.mindsphere.iot.exception.IotException"
message: "Size of payload should not be more than 100 kb"
path: "/api/iottimeseries/v3/timeseries"
NotFound:
<<: *ErrorTemplate
example:
timestamp: "2019-04-08T06:32:01.261+0000"
status: 404
error: "Not Found"
exception: "com.siemens.mindsphere.iot.exception.IotException"
message: "[6408] Unable to find the entity - entityId"
path: "/api/iottimeseries/v3/timeseries/entityId/propertySetName"
TooManyRequests:
<<: *ErrorTemplate
example:
timestamp: "2019-04-08T06:32:01.261+0000"
status: 429
error: "Too Many Requests"
exception: 'com.siemens.mindsphere.iot.exception.IotException'
message: "[429] Your request rate is too high, all calls will be rejected for a while"
path: "/api/iottimeseries/v3/timeseries/entityId/propertySetName"
Unauthorized:
type: object
properties:
id:
type: string
format: uuid
message:
type: string
example: Not authorized to access this resource.