DRIVR logo
API docs by Redocly

DRIVR Ingress API (1.0)

Download OpenAPI specification:Download

E-mail: support@drivr.cloud

This API is used to post datapoints or setpoints to DRIVR. You can send either single or multiple datapoints or setpoints. Batch processing is possible as well. In any case, you have to send the datapoints/setpoints in a list/array.

https://docs.drivr.cloud

Datapoint

Allows sending a single or multiple datapoints to DRIVR. The request may include an array, regardless if multiple datapoints are sent at once or only a single datapoint is sent. It also accepts single objects. Each item within the array needs to define to which timestream a value belongs. Additionally, a timestamp can be included to define, when a datapoint was measured. Setting a timestamp is recommended, if a local accurate clock exists from the sending device as otherwise the current time when the datapoint is processed is taken which may result in seconds of difference to the actual occurrence.

Add a single or multiple datapoints

Assigning to the timestream

Every value to be sent needs to have the system_uuid or system_code defined at the top level of the list. To further define, which timestream the value belongs to, either use the time_stream_uuid or a combination of the following properties:

  • component_code or component_uuid
  • service_code or service_uuid
  • characteristic_code or characteristic_uuid

See the example payload and the following table for possible combinations.

Attribute ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓
time_stream_uuid ✓
characteristic_code ✓ ✓ ✓ ✓
characteristic_uuid ✓ ✓ ✓ ✓
component_code ✓ ✓ ✓ ✓
component_uuid ✓ ✓ ✓ ✓
service_code ✓ ✓ ✓ ✓ ✓ ✓
service_uuid ✓ ✓
service_index ⍻ ⍻ ⍻ ⍻ ⍻ ⍻ ⍻ ⍻
system_(uuid|code) ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓
time ⍻ ⍻ ⍻ ⍻ ⍻ ⍻ ⍻ ⍻ ⍻
uuid ⍻ ⍻ ⍻ ⍻ ⍻ ⍻ ⍻ ⍻ ⍻
value ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓

✓: Required ⍻: Optional

Nested Values

If you want to send values of multiple characteristics from a single system, it can be useful to nest the value. With the data property you can add an additional level in your list bundle different values from different characteristics or even components of a single system in one item of your top level array. Please note that the timestream needs to be uniquely defined even if the different properties like component_code, service_uuid and characteristic_uuid are split among different levels in your array. It is also possible to overwrite in nested areas entries like system_code, component_code, and characteristic_uuid. The last item of the example payloads array does show this.

Add a timestamp to values

If you bundle up multiple values of a single timestream in a single request, make sure to assign different timestamps to it, so DRIVR can assign a unique time per value. You can add a timestamp by using the time property.

Add a uuid for simpler error handling

To make it simpler to assign a resulting error to a datapoint from the request, it is recommended to add a uuid to each value. This will be included in the error responses property names.

Value Datatypes

Some datatypes need to be encoded or formatted in a specific way.

DataType in DRIVR Format in JSON Format in msgpack
blob Base64 encoded String bin
boolean Boolean bool
date ISO 8601 Date String Timestamp extension type where UTC based midnight time is assumed
float Number float
integer Number int
json Stringified JSON str as Stringified JSON or map representing the JSON format directly
select Array of String array of str
string String str
time ISO 8601 DateTime String Timestamp extension type where the date is ignored.
timespan ISO 8601 Duration String Timestamp extension type
Authorizations:
bearerAuth
Request Body schema:
One of
Array
time_stream_uuid
string <uuid>
characteristic_code
string
characteristic_uuid
string <uuid>
component_code
string
component_uuid
string <uuid>
service_code
string
service_uuid
string <uuid>
system_code
string
system_uuid
string <uuid>
uuid
string <uuid>

UUID to assign the send datapoint or setpoint to a resulting error.

value
any

The value to be imported for the datapoint/setpoint.

Array of objects (NestedIngressData)
time
string <date-time>

Responses

Request samples

Content type
[
  • {
    },
  • {
    },
  • {
    }
]

Response samples

Content type
{
  • "code": "SOME_DATA_INVALID",
  • "message": "Some datapoints couldn't be imported.",
  • "stats": {
    },
  • "errors": {
    }
}

Setpoint

Allows sending a single or multiple setpoints to DRIVR. The request may include an array, regardless if multiple setpoints are sent at once or only a single setpoint is sent. It also accepts single objects. Each item within the array needs to define to which timestream a value belongs. Different to datapoints, a timestamp is not allowed to be set as this represents a request to change a setting via DRIVR on a device and always uses the current server time.

Add a single or multiple setpoints

Assigning to the timestream

Every value to be sent needs to have the system_uuid or system_code defined at the top level of the list. To further define, which timestream the value belongs to, either use the time_stream_uuid or a combination of the following properties:

  • component_code or component_uuid
  • service_code or service_uuid
  • characteristic_code or characteristic_uuid

See the example payload and the following table for possible combinations.

Attribute ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓
time_stream_uuid ✓
characteristic_code ✓ ✓ ✓ ✓
characteristic_uuid ✓ ✓ ✓ ✓
component_code ✓ ✓ ✓ ✓
component_uuid ✓ ✓ ✓ ✓
service_code ✓ ✓ ✓ ✓ ✓ ✓
service_uuid ✓ ✓
service_index ⍻ ⍻ ⍻ ⍻ ⍻ ⍻ ⍻ ⍻
system_(uuid|code) ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓
uuid ⍻ ⍻ ⍻ ⍻ ⍻ ⍻ ⍻ ⍻ ⍻
value ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓ ✓

✓: Required ⍻: Optional

Nested Values

If you want to send values of multiple characteristics from a single system, it can be useful to nest the value. With the data property you can add an additional level in your list bundle different values from different characteristics or even components of a single system in one item of your top level array. Please note that the timestream needs to be uniquely defined even if the different properties like component_code, service_uuid and characteristic_uuid are split among different levels in your array. The last item of the example payloads array does show this.

Add a timestamp to values

If you bundle up multiple values of a single timestream in a single request, make sure to assign different timestamps to it, so DRIVR can assign a unique time per value. You can add a timestamp by using the time property.

Add a uuid for simpler error handling

To make it simpler to assign a resulting error to a setpoint from the request, it is recommended to add a uuid to each value. This will be included in the error responses property names.

Value Datatypes

Some datatypes need to be encoded or formatted in a specific way.

DataType in DRIVR Format in JSON Format in msgpack
blob Base64 encoded String bin
boolean Boolean bool
date ISO 8601 Date String Timestamp extension type where UTC based midnight time is assumed
float Number float
integer Number int
json Stringified JSON str as Stringified JSON or map representing the JSON format directly
select Array of String array of str
string String str
time ISO 8601 DateTime String Timestamp extension type where the date is ignored.
timespan ISO 8601 Duration String Timestamp extension type
Authorizations:
bearerAuth
Request Body schema:
One of
Array
time_stream_uuid
string <uuid>
characteristic_code
string
characteristic_uuid
string <uuid>
component_code
string
component_uuid
string <uuid>
service_code
string
service_uuid
string <uuid>
system_code
string
system_uuid
string <uuid>
uuid
string <uuid>

UUID to assign the send datapoint or setpoint to a resulting error.

value
any

The value to be imported for the datapoint/setpoint.

Array of objects (NestedIngressData)

Responses

Request samples

Content type
[
  • {
    },
  • {
    },
  • {
    }
]

Response samples

Content type
{
  • "code": "SOME_DATA_INVALID",
  • "message": "Some datapoints couldn't be imported.",
  • "stats": {
    },
  • "errors": {
    },
  • "receipt_ids": [
    ]
}

Acknowledgement of a setpoint

Authorizations:
bearerAuth
Request Body schema:
state
required
string
Enum: "ACCEPTED" "REJECTED"
receipt_id
required
string
message
string

An optional message to add to the receipt if the Setpoint is rejected.

Responses

Request samples

Content type
{
  • "state": "REJECTED",
  • "receipt_id": "abc123",
  • "message": "Can not set this value."
}

Response samples

Content type
{
  • "invalid_state_change": "Setpoint with time_stream_uuid 7c2cb69b-3630-42a6-9cb1-24a45f76ace0 is already in REJECTED state"
}