Data Management

Streams

Data streams management

Create

Creates a data stream packet associated to a device in Altair SmartWorks.

URL: http://api.altairsmartcore.com/streams/
HTTP method: POST

Attributes:

Attribute Description
protocol (mandatory) Text. 50 characters max.
Comunication protocol. Used for checksum purposes.
Example: v1
device (mandatory) Text. 50 characters max.
Device unique identifier.
Example: d0001@smartcore
data (mandatory) Json.
The data itself
Example:
at (mandatory) Unix timestamp (UTC) or "now". When "now" is used, Altair SmartWorks will fill "at" value with reception date timestamp.
Data stream send date or automatically generated timestamp (using "now")
Examples: 1340001190 or "now"
checksum (optional) Text HMAC or SHA1. 40 chars.
Checksum control code.
Example: 8e0f1692c01e3333d0cdefe6840c5d61ffb7e3a6
Example: false
persist (optional) Boolean. Valid values: 0, 1, true or false.
Stream persistence, default true
Example: true

Response codes

Code Description
200 OK
{"response":"ok"}
401 Error
{"response":"error message"}
404 Resource not found
503 Service unavailable.

Request example:

POST http://api.altairsmartcore.com/streams/

Response example:

Show

Show data stream data

URL: http://api.altairsmartcore.com/streams/-- ID_developer --/
HTTP method: GET
Response: json/xml

Response codes

Code Description
200 Operation successfull
Possible values:
- JSON Stream object
400 Request not valid
Possible values:
- code: 4004 message: format parameter invalid details:{field: error message, …..}
404 Resource not found
503 Service unavailable.
- code: 5031 message: BD error details:
- code: 5032 message: exception details: {message: }
List

Data stream list with 1000 max elements

URL: http://api.altairsmartcore.com/streams/
HTTP method: GET
Response: json/xml

Parameters:

Attribute Description
_t (optional) Text: "str" or "sta".
Filter list result by data streams (using "str") or status streams (using "sta"). If ommited, all streams (data and status) are listed.
Example: "str" list only data streams.
protocol (optional) Text. 50 characters max.
Filter list result by field protocol.
Example: v1
device (optional) Text. 50 characters max.
Filter list result by field device.
Example: d0001@smartcore
at (optional) Timestamp. 50 characters max.
Filter list result by field at.
Example: 1337009328
to and from modificators allows to specify a range. Extreme values are included.
Example: at_to=1337009328
owner (optional) username.
Filter list result by field owner.
Example: jlopez
updater (optional) username.
Filter list result by field updater.
Example: jlopez
created_at (optional) Timestamp.
Filter list result by field created_at.
Example: 1337009328
to and from modificators allows to specify a range. Extreme values are included.
Example: created_at=1337009328
max (optional) Integer. Values between 1 and 1000.
Defines the number of results to be returned. Max and default value is 1000.
Example: 250
sort (optional) Field name.
Sort the result by the given field. Default value is device.
Example: creation_date
order (optional) Integer. Valid values: -1 or 1
Result order criteria: -1 for descending and 1 for ascending.
Example: -1
offset (optional) Integer.
Result offset. List will begin at the given offset.
Example: 100

Response codes

Code Description
200 Operation successfull
Possible values:
- total_documents: result numbers result: Set of JSON Stream objects
400 Request not valid
Possible values:
- code: 4004 message: format parameter invalid details:{field: error message, …..}
503 Service unavailable.
- code: 5031 message: BD error details:
- code: 5032 message: exception details: {message: }
Delete

Removes the stream indicated permanently

URL: http://api.altairsmartcore.com/streams/-- ID_developer --/
HTTP method: DELETE

Response codes

Code Description
200 Operation successfull
Possible values:
- code: 2004 message: stream deleted details:
404 Resource not found
503 Service unavailable.
- code: 5031 message: BD error details:
- code: 5032 message: exception details: {message: }

Request example:

DELETE http://api.altairsmartcore.com/streams/-- ID_developer --/

Response example:

Status Streams

Status streams management.

Create

Creates a status stream packet associated to a device in Altair SmartWorks.

URL: http://api.altairsmartcore.com/status
HTTP method: POST

Attributes:

Attribute Description
protocol (mandatory) Text. 50 characters max.
Comunication protocol. Used for checksum purposes.
Example: v1
device (mandatory) Text. 50 characters max.
Device unique identifier.
Example: d0001@smartcore
data (mandatory) Json.
The data itself. Here is the difference from a data stream. Keys can be devices file names (configuration files can be associated to devices) with a version number as value. When a key matches a devices file name, Altair SmartWorks will compare its version and will return a 0 if version match (0 means no update needed) or 1 if version does not match, which means that for that file versions are different. If a key doesnt correspond to a devices file, nothing will be returned (0 nor 1). All data is stored in Altair SmartWorks DB and is accessible from listeners.

Example:
Supposing a context in which the requested device d0001@smartcore has 3 associated files: dynamic_conf with version 1.0, static_conf with version 1.3 and firmware with version 0.1 The request with the following data:

Will return:

Which means that dynamic_conf is 0 (no update needed), static_conf is 1 (update needed) and firmware is 0 (no update needed). battery_level is ignored in response because it does not match any devices file.
at (mandatory) Unix timestamp (UTC) or "now". When "now" is used, Altair SmartWorks will fill "at" value with reception date timestamp.
Status stream send date or "now"
Example: 1340001190 or "now"
checksum (optional) Text HMAC or SHA1. 40 chars.
Checksum control code.
Example: 8e0f1692c01e3333d0cdefe6840c5d61ffb7e3a6
Example: false
persist (optional) Boolean. Valid values: 0, 1, true or false.
Status stream persistence, default true
Example: true

Response codes

Code Description
200 OK
{"response":"-- files update codes --"}
401 Error
{"response":"error message"}
404 Resource not found
503 Service unavailable.
Show

Show status stream data. As a status stream is treated as a normal data stream, management URLs are the same.

URL: http://api.altairsmartcore.com/streams/-- ID_developer --/
HTTP method: GET
Response: json/xml

Response codes

Code Description
200 Operation successfull
Possible values:
- JSON Status stream object
400 Request not valid
Possible values:
- code: 4004 message: format parameter invalid details:{field: error message, …..}
404 Resource not found
503 Service unavailable.
- code: 5031 message: BD error details:
- code: 5032 message: exception details: {message: }
List

Status stream list with 1000 max elements. As a status stream is treated as a normal data stream, management URLs are the same, except for the filter parameter.

URL: http://api.altairsmartcore.com/streams/?_t=sta
HTTP method: GET
Response: json/xml

Parameters:

Attribute Description
_t (optional) Text: "str" or "sta".
Filter list result by data streams (using "str") or status streams (using "sta"). If ommited, all streams (data and status) are listed.
Example: "str" list only data streams.
protocol (optional) Text. 50 characters max.
Filter list result by field protocol.
Example: v1
device (optional) Text. 50 characters max.
Filter list result by field device.
Example: d0001@smartcore
at (optional) Timestamp. 50 characters max.
Filter list result by field at.
Example: 1337009328
to and from modificators allows to specify a range. Extreme values are included.
Example: at_to=1337009328
owner (optional) username.
Filter list result by field owner.
Example: jlopez
updater (optional) username.
Filter list result by field updater.
Example: jlopez
created_at (optional) Timestamp.
Filter list result by field created_at.
Example: 1337009328
to and from modificators allows to specify a range. Extreme values are included.
Example: created_at=1337009328
max (optional) Integer. Values between 1 and 1000.
Defines the number of results to be returned. Max and default value is 1000.
Example: 250
sort (optional) Field name.
Sort the result by the given field. Default value is device.
Example: creation_date
order (optional) Integer. Valid values: -1 or 1
Result order criteria: -1 for descending and 1 for ascending.
Example: -1
offset (optional) Integer.
Result offset. List will begin at the given offset.
Example: 100

Response codes

Code Description
200 Operation successfull
Possible values:
- total_documents: result numbers result: Set of JSON status objects
400 Request not valid
Possible values:
- code: 4004 message: format parameter invalid details:{field: error message, …..}
503 Service unavailable.
- code: 5031 message: BD error details:
- code: 5032 message: exception details: {message: }

Note: If you want to list streams of a specific device, you can also do it this way (List Streams)

Delete

Removes the status stream indicated permanently. As a status stream is treated as a normal data stream, management URLs are the same.

URL: http://api.altairsmartcore.com/streams/-- ID_developer --/
HTTP method: DELETE

Response codes

Code Description
200 Operation successfull
Possible values:
- code: 2004 message: stream deleted details:
404 Resource not found
503 Service unavailable.
- code: 5031 message: BD error details:
- code: 5032 message: exception details: {message: }

Note: If you want to delete a streams set of a specific device, you can also do it this way (Delete Streams)

Triggers

Triggers management in Altair SmartWorks

Create

Create trigger

URL: http://api.altairsmartcore.com/triggers/
HTTP method: POST

Attributes:

Attribute Description
name (mandatory) Text. 50 characters max.
Unique.
Trigger name.
Example: m001
description (optional) Text. 200 characters max.
Trigger description.
Example: Temperature sensor
max_retries (mandatory) Integer. Default 5
Max number of retries if push data fails.
Example: 15
push_frequency (mandatory) Integer. Default 0
Number of minutes to wait to push the data.
Example: 60
enabled (mandatory) Boolean. Valid values: 0, 1, true or false.
Model enabled, default true
Example: true
id_service (mandatory) Service id_developer
Example: parkingservice@smartcore
external_configuration (mandatory) Json
Detailed trigger configuration
JSON must be composed by:
"url": (mandatory) text
"verb": (mandatory) text, on of get, post, put or delete
"headers": (optional) key-values
"params": (optional) key-values
"payload": (optional) text. 1024 characters max.
"http_auth": (optional) JSON with
"user": text
"password": text

Response codes

Code Description
200 Operation successfull
Possible values:
- code: 2001 message: trigger persisted details:
400 Request not valid
Possible values:
- code: 4001 message: Json bad formed details:
- code: 4003 message: validation error details: {field: error message,...}
404 Resource not found
503 Service unavailable.
- code: 5031 message: BD error details:
- code: 5032 message: exception details: {message: }
Show

Trigger show

URL: http://api.altairsmartcore.com/triggers/-- ID_developer --/
HTTP method: GET
Response: json/xml

Response codes

Code Description
200 Operation successfull
Possible values:
- Trigger JSon/xml
400 Request not valid
Possible values:
- code: 4004 message: format parameter invalid {field: error message,...}
404 Resource not found
503 Service unavailable.
- code: 5031 message: BD error details:
- code: 5032 message: exception details: {message: }
List

Triggers list, max. 1000

URL: http://api.altairsmartcore.com/triggers/
HTTP method: GET
Response: json/xml

Parameters:

Attribute Description
name (optional) Text. 50 characters max.
Filter list result by field name.
Example: t001
enabled (optional) Boolean. Valid values: 0, 1, true or false.
Filter list result by field enabled.
Example: true
owner (optional) username.
Filter list result by field owner.
Example: jlopez
updater (optional) username.
Filter list result by field updater.
Example: jlopez
created_at (optional) Timestamp.
Filter list result by field created_at.
Example: 1337009328
to and from modificators allows to specify a range. Extreme values are included.
Example: created_at=1337009328
max (optional) Integer. Values between 1 and 1000.
Defines the number of results to be returned. Max and default value is 1000.
Example: 250
sort (optional) Field name.
Sort the result by the given field. Default value is name.
Example: creation_date
order (optional) Integer. Valid values: -1 or 1
Result order criteria: -1 for descending and 1 for ascending.
Example: -1
offset (optional) Integer.
Result offset. List will begin at the given offset.
Example: 100

Response codes

Code Description
200 Operation successfull
Possible values:
- total_documents:result numbers result: Trigger JSON objects set
400 Request not valid
Possible values:
- code: 4004 message: format parameter invalid {field: error message,...}
503 Service unavailable.
- code: 5031 message: BD error details:
- code: 5032 message: exception details: {message: }
Update

Trigger update

URL: http://api.altairsmartcore.com/triggers/-- ID_developer --/
HTTP method: PUT

Response codes

Code Description
200 Operation successfull
Possible values:
- code: 2005 message: trigger updated details:Model JSON object
400 Request not valid
Possible values:
- code: 4001 message: nonexistent file details:
- code: 4003 message: validation error details:{field: error message,...}
- code: 4004 message: format parameter invalid details:{field: error message,...}
- code: 4005 message: concurrency error details:{version: }
404 Resource not found
503 Service unavailable.
- code: 5031 message: BD error details:
- code: 5032 message: exception details: {message: }
Delete

Trigger delete

URL: http://api.altairsmartcore.com/triggers/-- ID_developer --/
HTTP method: DELETE

Response codes

Code Description
200 Operation successfull
Possible values:
- code: 2004 message: trigger deleted details:
404 Resource not found
503 Service unavailable.
- code: 5031 message: BD error details:
- code: 5032 message: exception details: {message: }