Difference between revisions of "Datonis:Using the Datonis Application API"

Revision as of 12:00, 1 July 2017

Datonis provides an Application API for applications and scripts to integrate with the platform. It is a fully RESTful API. The data interchange format is JSON.

The API is currently at version 3.0. We provide backward compatibility to the previous major version of the API. Currently version 2.0 and 3.0 are supported. It is highly recommended to use version 3.0 if you are starting out.

Detailed documentation of the Datonis Application API

The example usage of the API in this article assume that you are using cURL. You can also use any HTTP library of your choice.

Authentication

There are two ways in which you can authenticate with Datonis.

Username and Password

You can use a username and password to log in and use the API. The API will restrict access to only those entities that the user has access to. This tutorial shows you how to create users and roles. You can then use the API as shown.

curl -X POST -H "Content-Type:application/json" -d '{"email":"<registered-email>","password":"<password>"}' 'https://api.datonis.io/api_sign_in'

And the response if the login is successful

{"success":true,"auth_token":"nwvZ00oLf4MHtc-BFL_4Qw","email":"<email>","role":"admin","time_zone":"time_zone","user_key":"user_key","sign_in_count":10,"datonis_role":{"abilities":[0],"account_admin":true,"datonis_role_key":"role_key","name":"Account Admin","permissions":[{"class":"all","operation":null,"seqno":0}],"users_count":1,"key_pairs_count":0,"created_at":1453116133,"updated_at":1453116133},"organisation":{"name":null,"organisation_key":null,"license":{"license_key":"39759ac4tbbc7165572125658576etcc88447a21"}}}

The value that is most relevant is the alphanumeric auth_token. You should keep the value of the auth_token for use in every subsequent API calls.The auth_token expires if there is 30 minutes of inactivity. In that case, you need to re-login and get a new auth token.

API Keys

You can also generate an API key and use that. You can go to Key Pairs on the Access Control menu and generate a key-pair and assign it to a suitable role. Give it a suitable expiry date. The access key needs to be passed in the request header as "X-Access-Key"

curl -X GET  -H "X-Access-Key:<access-key>" https://api.datonis.io/api/v3/things

You can use any one these authentication methods to authenticate. The API documentation would have references to the auth_token based authentication. You can replace that by the access key based authentication as explained above.

Pagination

You can specify the page size in requests that support pagination. Here is an example of fetching things. This can be applied for all requests that support pagination.

curl -X GET  -H "X-Access-Key:<access-key>" -d '{"per":"2","page":"1"}' https://api.datonis.io/api/v3/things

Here you can specify two parameters. per indicates the results per page. page indicates the page to fetch

Pretty Printing

Pretty printing returns the JSON result in well formatted manner, making it easy to read. You can set this field when trying out the APIs. You should set this to false when calling the API from a program to reduce bytes sent over the wire as indentation introduces whitespace in the response.

Here is a paginated request with pretty printing turned on. You set the pretty property to true.

curl -X GET  -H "X-Access-Key:<access-key>" -d '{"per":"2","page":"1", "pretty": true}' https://api.datonis.io/api/v3/things

Querying Thing Data

Querying Thing Data can be done in two ways.

Querying Raw Thing Data

Raw data represents every metric that was sent to Datonis by a Thing. You can use the following query to retrieve raw data. You can only query for 24 hours worth of data for a single Thing using this API. 

Here is a sample that queries every every metric for a Thing between the 29th of February to the 1st of March 2016 from 1pm to 1pm.

curl -X POST -H "Content-Type:application/json" --header 'X-Auth-Token:<auth_token>' -d '{"thing_key":"<thing_key>", "from":"2016/02/29 13:00:00", "to":"2016/03/01 13:00:00", "time_zone":"UTC" , "time_format":"str", "per":"10", "pretty":true}' 'https://api.datonis.io/api/v3/datonis_query/thing_data'

Detailed API documentation on querying raw data

Querying Aggregated Thing Data

Datonis performs real-time aggregations on Thing metrics. What this means is that if you are pushing Thing data at a velocity that is greater than once a minute, Datonis will automatically roll that up. Datonis has the following levels of aggregation

• Minute: Metrics aggregated at a minute level. For instance, if you are streaming a metric every 15 seconds, say m15, m30, m45 and m60. Datonis will create a single aggregated metric for that minute. The aggregated metric will have sum, min, max, avg and count. In this particular case, sum = (m15+m30+m45+m60), avg = (m15+m30+m45+m60)/4, count = 4 and so on.
• Hour: Metrics aggregated at an hourly level.
• Day: Metrics aggregated at a daily level.
• Month: Metrics aggregated at a monthly level.

Here is a sample that queries the aggregated metrics for a Thing between the 29th of February to the 1st of March 2016 from 1pm to 1pm. It groups the data by the hour.

curl -X POST -H "Content-Type:application/json" --header 'X-Auth-Token:wPqDyDKrdLuUix3v4J_arQ' -d '{"idle_time_required":true,"time_grouping":"hour","time_zone":"UTC","thing_keys":["91c8ee458t"],"from":"2016/02/29 13:00:00","to":"2016/03/01 13:00:00" }' 'https://api.datonis.io/api/v3/datonis_query/thing_aggregated_data'

Detailed API documentation on querying aggregated data