API Documentation

Documentation version: 1.2.8

Last updated: 12 Jan 18 20:05 PST

Overview

The DB4IoT API provides programmatic access for the pushing and querying of data, as well as management of entities such as devices, users, datasources, and more. It allows for fine-grained control over what users and devices may do through a system of abstract (create a device, create a user, etc.) and object (push data to datasource XYZ, update user 123) permissions.

Making requests

All API requests should be directed at api.db4iot.com. Unless otherwise specified for a specific API call, all path components of the URL should be prefixed by /v1. A valid example request URL to an SSL-enabled HTTP endpoint would thus look like: https://api.db4iot.com/v1/customer/46b16d5f-dc92-422d-982b-468aea8ced11.


Authentication

As part of the HTTP API, certain headers OR query string parameters must be provided in order for a request to succeed. What follows is a list of these headers and query string parameters, how they are used, and how you should construct them.

There is no need to provide both headers and query string parameters. Select one approach per request (which you choose can vary between requests, at your discretion) and use that exclusively for that request.

HTTP Headers

  • Authorization

    The HTTP standard Authorization header is used for passing the API key and authentication hash. A valid formatted example looks like this: fnGElwNppETDPnbQdXh0ocw9lDCDc9:SgyP1qELUeO2JrUy8MRdjcdSLgLXCW0m4z6akk5O+ek=, and has the general format (without brackets) of {API key}:{HMAC signature}. For information on how to calculate the HMAC signature for this header, see HMAC authentication examples.

  • Content-Type

    The HTTP standard Content-Type header is used as part of HMAC authentication, and indicates the type of data being sent in via POST, PUT, and DELETE. The supported content types are:

    • text/plain
    • text/plain; charset=UTF-8
    • application/json
    • application/json; charset=UTF-8
    • application/x-www-form-urlencoded

    A note for web application developers

    When sending requests via POST, you should prefer to use the text/plain family of content types. Doing so will prevent the browser from issuing unnecessary preflight OPTIONS requests, which reduces your API usage and improves responsiveness of your application. If you choose to use this optimization, it must be paired with the use of query parameter-based authentication rather than header-based. For more information, refer to the MDN documentation located here: MDN CORS Simple Requests.

  • X-D4i-Date

    The X-D4i-Date header is used for the prevention of replay attacks. Callers of the API must have their system clocks synchronized to within 15 minutes of the servers time (using NTP is the best way to ensure this), or they will not be able to provide valid 'Date' header values and the request will fail.

    The value provided for this header MUST be the same value provided in the signing string used to create your HMAC hash.

    This header is provided as a custom header because spec-compliant XMLHTTPRequest-based clients (such as jQuery) will not allow the setting of unsafe headers such as the standard Date header.

    A valid formatted example looks like this: 2015-09-15T15:50:39-07:00, and is an ISO 8601 (RFC3339) timestamp.

HTTP Query string parameters

If your HTTP client does not support the setting of the one or more of the above headers, you may optionally provide the following query string parameters as replacements. This is commonly the case with some libraries, such as Leaflet (a mapping library commonly used to request tiles from DB4IoT).

In general, prefer the use of HTTP Headers instead of query string parameters. Headers benefit from header compression and make URLs easier to read.

A note for web application developers

The exception to preferring header-based authentication is when your requests originate from a web browser. In order to prevent your web application from sending OPTIONS preflights for most requests, you should opt for the use of query parameters. Doing so (in combination with the use of text/plain or text/plain; charset=UTF-8 Content-Type headers will dramatically improve overall responsiveness of your application. For more information on CORS preflighting, see the MDN documentation located here: MDN CORS Simple Requests.

  • X-D4i-APIKey

    This parameter contains an API key of the user or device making the request. A valid formatted example looks like this: X-D4i-APIKey=fnGElwNppETDPnbQdXh0ocw9lDCDc9.

    Taken as a component of an Authorization header, this would be the characters prior to the :.

  • X-D4i-Signature

    This parameter contains a calculated HMAC hash signature for the request. A valid formatted example looks like this: X-D4i-Signature=SgyP1qELUeO2JrUy8MRdjcdSLgLXCW0m4z6akk5O.

    Taken as a component of an Authorization header, this would be the characters after the :.

    Note that you should escape this hashed value before sending it. The signature will often contain characters like '+' that will not be interpreted correctly and result in a signature mismatch.

  • X-D4i-Date

    This parameter contains an ISO 8601 (RFC3339) timestamp. A valid formatted example looks like this: X-D4i-Date=2015-09-15T15:50:39-07:00.

    As with the X-D4i-Date header, the value provided for this parameter MUST be the same value provided in the signing string used to create your HMAC hash.

API keys

API keys are issued to users and devices and enable API access. One or more keys may be assigned to each user or device, but each key may only be assigned to a single user or device. Keys may be assigned or removed from users and devices at will, and are a useful way to scope a set of permissions. API keys are necessary but not sufficient to grant API access; as part of HMAC authentication, a secret token is also required in the hash header. API keys are assigned zero or more permissions, which may be of the abstract or object variety. As part of executing an API call, the API key is checked for the required permissions before access is allowed. See Permissions for more information on how permissions are designed. For API key manipulation endpoints, see the Key API.

Secret token

When a user or device is created, a unique secret token is assigned to it. The secret is used as part of HMAC authentication. Only one secret token may be assigned to a user or device at a time. No permissions are attached to the secret token.

Security of APIs that return a secret token

APIs that return users or devices will also return the secret token as part of their response. It is your responsibility to engage these APIs only over an encrypted connection to avoid leaking the secret token!

HMAC

Through the use of HMAC authentication, the API enhances the general security of your access and provides strong protection against masquerading and replay attacks. Due to the nature of HMAC, it is possible to perform requests over plain-text network protocols such as HTTP and maintain reasonable guarantees that your API access will not be compromised by attackers. This is typically used for devices that do not support TLS.

Content sent over HTTP is not private

If you choose to trasmit data directly to us through an unencrypted connection, be aware that any data you pass to us can be easily seen by an attacker. HMAC can only protect the integrity of your API access, not the privacy of the data you send to us. If you would like to also have assurances that the data you send is private, use an encrypted protocol such as HTTPS.

HMAC is built upon the following principles:

  • a public API key that can be transmitted safely over unencypted connections
  • a secret token that only the device/user and our systems know
  • a set of known request parameters such as method, body content, content MD5, etc.
  • hashing a string of the secret and known parameters in a specific order
  • reconstructing the hash server-side and ensuring a match

Building your HMAC signature

As described in the Headers section, the Authorization header (which contains your HMAC signature) has the form: {API key}:{HMAC signature}. The API key is your user or device API key without any transformation applied. The HMAC signature is calculated with the following pseudo-code format:

Do not mistakenly provide the secret token instead of the API key!

You secret token should never be provided in plain text in any API request. Only the API key is safe to expose in requests, specifically as the first colon-separated component of the Authorization string.

hmac_signature = base64string(hmac_sha512(secret key, utf8encoded(string_to_sign)))

Implementations of your language's construction of this signature will vary, so let's break down the pieces so as to aid you in quickly creating a correct hash.

  • hmac_signature - the result of the function composition, which is of type string. This result is what goes in the "HMAC signature" piece of your Authorization header {API key}:{HMAC signature}
  • base64string(...) - a function that takes an array of bytes and converts it to a base64 encoded string.
  • hmac_sha512(...) - a function that constructs an array of bytes representing an HMAC signature using the SHA512 algorithm. Most language implementations will take two parameters: the algorithm to use (in this case, always SHA512), and a key (in this case, your device or user secret_key.
  • secret_key - your device or user secret_token.
  • utf8encoded(...) - in some implementations, "string_to_sign" may already be utf-8 encoded. If your language does not produce strings encoded in this manner naturally, you must use a function to convert your "string_to_sign" into this encoding.
  • string_to_sign - the newline-separated concatenation of all required parameters that will contribute to the resulting HMAC signature. The list of required parameters is listed below.

Signing string parameters

In the previous section we learned how to build a function that produces a correct signature. The following defines the parameters that go into the "string_to_sign" piece of that function.

HTTP Method\n
Content MD5 sum\n
Content-Type\n
Date, ISO 8601 (RFC3339) timestamp\n
Full path requested against

A description of each parameter is as follows:

  • HTTP method - the HTTP method used for this request. Must match the actual method used.
  • Content MD5 sum - an MD5 checksum of the HTTP body being sent. In the case where no body is sent, use an empty string.
  • Content type - content type of the body being sent; for requests with a body this is text/plain, text/plain; charset=UTF-8, application/json, or application/json; charset=UTF-8. Otherwise, use an empty string.
  • Date - An ISO 8601 (RFC3339) formatted timestamp within 15 minutes of server time. In order to ensure your dates are within an acceptable range, you should use a standard internet time source such as NTP. This parameter is used to prevent replay attacks outside of a 15-minute interval.
  • URL Path - The path of the URL you are requesting, e.g. /v1/user/123

Examples

Use the following examples to verify the correctness of your signature generation function for both requests with bodies (PUT, POST, DELETE) and those without (GET, HEAD, OPTIONS).

A signing string for a POST request with a body:

POST\n
0e0246f569a0b1d5ba4e8107c35a88f5\n
application/json\n
2016-04-28T11:00:46-07:00\n
/v1/customer/0ffcc3ee-9f76-41f8-80fb-182682c173d5/datasources

The correct signature output for the above signing string and secret token xtnyowoqpooktxsnlrozkloykvpvlzor is qr2FjYdkKAyOv1qE7LXzkzM0JmFhvn8Fp/R/Srzu9pie7/P6tALiCRD5zZHUUhi6oBzzs2X7am7RRJGmXC3Uig==

A GET request, which does not contain a body:

GET\n
\n
\n
2016-04-28T11:00:36-07:00\n
/v1/device/fa854fab-c8b1-436d-a1ef-3b50fa0c1d0f

The correct signature output for the above signing string and secret token xtnyowoqpooktxsnlrozkloykvpvlzor is uw5hbbV7YPi8XCCJpmZDCQsxOchYPrgDC+pOAkMnTTZUX8M36mgPuQJiSQ6fZREiBTMDA1OfImJfBnL3VtnaRA==

Summary

Putting it all together from the last example, assuming an API key of tlwypqxkvtvwvwtzuwvwmrvxsrxmltkq a valid request would look like: GET /v1/device/fa854fab-c8b1-436d-a1ef-3b50fa0c1d0f; Authorization HTTP Header: tlwypqxkvtvwvwtzuwvwmrvxsrxmltkq:uw5hbbV7YPi8XCCJpmZDCQsxOchYPrgDC+pOAkMnTTZUX8M36mgPuQJiSQ6fZREiBTMDA1OfImJfBnL3VtnaRA==

Permissions

For permission manipulation endpoints, see the Keys and Permissions API.


Administrative API

Overview

This collection of APIs enables manipulation of a variety of objects in the system, including: customers, users, devices, datasource schemas, datasources, keys, and permissions. Each command may require one or more abstract or object permissions, which your key must possess to successfully make a given request. As with all APIs, requests to these endpoints must pass HMAC authentication and include all required headers.

Customer

Overview

A customer is the top-level scoping object for many object types. Users, devices, datasources, etc. are all owned by a customer. When granted access to the DB4IoT API, you will be provided with a unique customer identifier along with the root admin key and secret. These pieces of information are sufficient to access the entire customer space of objects, and to begin creating new objects under the control of your customer.

Available APIs

POST /customer/{customer_id}/datasources

Route parameters

customer_id uuid

  • Customer ID

Body parameters

datasource_schema_id uuid

  • The datasource schema to use for the new datasource.

name string

  • The name to give to the new datasource.

Description

This endpoint is used for creating datasources, which are used to store and query data.

Response definition

datasource_id

  • The unique identifier for the datasource.

datasource_schema_id uuid

  • The unique identifier for the schema used to create the datasource.

customer_id uuid

  • The unique identifier for the customer that owns this datasource.

engine_type string

  • The engine storage backing the datasource.

engine_type_id integer

  • The internal identifier for the engine_type.

engine_version string

  • The major version of the engine backing the datasource.

name string

  • The name given to this datasource. Must be unique.

permissions array [permission :: object]

  • The set of object permissions that apply to this datasource.

Examples

Request

POST /customer/13855d51-5922-4a00-a9fe-dd87204c8721/datasources

Body

{"data":{"datasource_schema_id":"250a5770-b2b4-4d4a-80bc-27e6f2748a6f","name":"Datasource 1"}}

Response

{"status":"ok","data":{"datasource":{"customer_id":"13855d51-5922-4a00-a9fe-dd87204c8721","datasource_id":"6edf5b5f-d438-4796-84c8-cf600f036424","datasource_schema_id":"250a5770-b2b4-4d4a-80bc-27e6f2748a6f","engine_type":"ephemeris","engine_type_id":2,"engine_version":"1.0","name":"Datasource 1","permissions":[{"action":"modify","action_detail":"modify_datasource","permission_id":61339,"permission_type_id":51,"target_type":"datasource"},{"action":"modify","action_detail":"modify_schema_for_datasource","permission_id":61340,"permission_type_id":52,"target_type":"datasource"},{"action":"deactivate","action_detail":"deactivate_datasource","permission_id":61341,"permission_type_id":53,"target_type":"datasource"},{"action":"activate","action_detail":"activate_datasource","permission_id":61342,"permission_type_id":54,"target_type":"datasource"},{"action":"delete","action_detail":"delete_datasource","permission_id":61343,"permission_type_id":55,"target_type":"datasource"},{"action":"unlink","action_detail":"unlink_schema_from_datasource","permission_id":61344,"permission_type_id":56,"target_type":"datasource"},{"action":"purge","action_detail":"purge_datasource","permission_id":61345,"permission_type_id":57,"target_type":"datasource"},{"action":"instantiate","action_detail":"instantiate_datasource","permission_id":61346,"permission_type_id":58,"target_type":"datasource"},{"action":"read","action_detail":"get_datasource","permission_id":61347,"permission_type_id":59,"target_type":"datasource"},{"action":"read","action_detail":"get_datasource_data_nodes","permission_id":61348,"permission_type_id":60,"target_type":"datasource"},{"action":"append data","action_detail":"ingest_data","permission_id":61349,"permission_type_id":88,"target_type":"datasource"},{"action":"append data","action_detail":"ingest_batch","permission_id":61350,"permission_type_id":90,"target_type":"datasource"},{"action":"delete data","action_detail":"delete_range","permission_id":61351,"permission_type_id":91,"qualifier":"timestamp range","target_type":"datasource"},{"action":"read raw","action_detail":"query_raw","permission_id":61352,"permission_type_id":92,"qualifier":"raw","target_type":"datasource"},{"action":"read rollup","action_detail":"query_rollup","permission_id":61353,"permission_type_id":93,"qualifier":"rollup","target_type":"datasource"},{"action":"read topn","action_detail":"query_topn","permission_id":61354,"permission_type_id":94,"qualifier":"topn","target_type":"datasource"},{"action":"read groupby","action_detail":"query_groupbys","permission_id":61355,"permission_type_id":95,"qualifier":"groupby","target_type":"datasource"}]}}}
POST /customer/{customer_id}/devices

Route parameters

customer_id string

  • Customer id to create the device for
  • Must be the same customer as that of the API key owner

Body parameters

name string

  • The name to give the device
  • Must be unique within the customer

Description

This endpoint is used for creating devices and attaching them to customers.

Response definition

customer_id uuid

  • The unique identifier for the customer that owns this device

device_id uuid

  • The unique identifier for this device

name string

  • The name of the device

permissions array [permission :: object]

  • The set of object permissions that apply to this device
  • See Keys and Permissions for response definition

secret_token string

  • The secret token for this device, used as part of API authentication

Examples

Request

POST /customer/13855d51-5922-4a00-a9fe-dd87204c8721/devices

Body

{"data":{"name":"new.device"}}

Response

{"status":"ok","data":{"device":{"customer_id":"13855d51-5922-4a00-a9fe-dd87204c8721","device_id":"3a4bf4be-5cc2-4a88-b2a6-fdf888b6a007","name":"new.device","permissions":[{"action":"modify","action_detail":"modify_device","permission_id":98485,"permission_type_id":18,"target_type":"device"},{"action":"deactivate","action_detail":"deactivate_device","permission_id":98486,"permission_type_id":19,"target_type":"device"},{"action":"activate","action_detail":"activate_device","permission_id":98487,"permission_type_id":20,"target_type":"device"},{"action":"delete","action_detail":"delete_device","permission_id":98488,"permission_type_id":21,"target_type":"device"},{"action":"read","action_detail":"get_device","permission_id":98489,"permission_type_id":22,"target_type":"device"},{"action":"read device","action_detail":"get_device_keys","permission_id":98490,"permission_type_id":38,"target_type":"device"},{"action":"read","action_detail":"get_device_datasource_schemas","permission_id":98491,"permission_type_id":49,"qualifier":"schemas","target_type":"device"},{"action":"read device","action_detail":"get_device_datasources","permission_id":98492,"permission_type_id":62,"target_type":"device"}],"secret_token":"krlpnrztlwyzpkxosstuzlywuonxnums"}}}
POST /customer/{customer_id}/users

Route parameters

customer_id string

  • Customer id to create the user for
  • Must be the same customer as that of the API key owner

Body parameters

name string

  • The name to give the user
  • Must be globally unique, and is generally an email address

email string

  • The contact email for the user

Description

This endpoint is used for creating users and attaching them to customers.

Response definition

customer_id uuid

  • The unique identifier for the customer that owns this user

email email

  • The email address for this user

user_id uuid

  • The unique identifier for this user

is_superuser boolean

  • Whether or not the user is a superuser

name string

  • The name of the user

permissions array [permission :: object]

  • The set of object permissions that apply to this user
  • See Keys and Permissions for response definition

secret_token string

  • The secret token for this user, used as part of API authentication

Examples

Request

POST /customer/13855d51-5922-4a00-a9fe-dd87204c8721/users

Body

{"data":{"name":"new.user","email":"new.user@hello.com"}}

Response

{"status":"ok","data":{"user":{"customer_id":"13855d51-5922-4a00-a9fe-dd87204c8721","email":"new.user@hello.com","is_superuser":false,"name":"new.user","permissions":[{"action":"modify","action_detail":"modify_user","permission_id":98477,"permission_type_id":11,"target_type":"user"},{"action":"deactivate","action_detail":"deactivate_user","permission_id":98478,"permission_type_id":12,"target_type":"user"},{"action":"activate","action_detail":"activate_user","permission_id":98479,"permission_type_id":13,"target_type":"user"},{"action":"delete","action_detail":"delete_user","permission_id":98480,"permission_type_id":14,"target_type":"user"},{"action":"read","action_detail":"get_user","permission_id":98481,"permission_type_id":15,"target_type":"user"},{"action":"read user","action_detail":"get_user_keys","permission_id":98482,"permission_type_id":39,"target_type":"user"},{"action":"read","action_detail":"get_user_datasource_schemas","permission_id":98483,"permission_type_id":48,"qualifier":"schemas","target_type":"user"},{"action":"read user","action_detail":"get_user_datasources","permission_id":98484,"permission_type_id":63,"target_type":"user"}],"secret_token":"stvpomurznstkwotywzvsvsnvlozvxoo","user_id":"0f267db6-0f9a-4a07-98cd-addf5e834f6a"}}}
GET /customer/{customer_id}

Route parameters

customer_id string

  • Customer id to retrieve

Query string parameters

with_permissions boolean

  • Include or omit the permission space for this object

Description

This command returns information about a customer, provided that the requester has object permissions to view this information. If "with_permissions" is true, the space of object permissions that apply to the customer will be returned as well.

Response definition

customer_id uuid

  • The unique identifier for this customer

email email

  • The email address for this customer

name string

  • The name of the customer

created timestamp

  • An ISO 8601 timestamp for when the customer was created

is_active boolean

  • Whether or not this customer is active and usable

is_deleted boolean

  • Whether or not this customer is deleted and no longer valid

admin_user_id uuid

  • The root admin user id for this customer

admin_user_api_key string

  • The root admin user API key for this customer

permissions array [permission :: object]

  • The set of object permissions that apply to this customer
  • See Keys and Permissions for response definition

Examples

Request

GET /customer/13855d51-5922-4a00-a9fe-dd87204c8721?with_permissions=true

Response

{"status":"ok","data":{"customer":{"admin_user_api_key":"rvpwtvsxvnlwtzxltoxvxvomqyqlmwwy","admin_user_id":"967119b2-0e68-4b41-adaf-a35aa5b44a81","created":"2016-04-19 19:35:21.441437","customer_id":"13855d51-5922-4a00-a9fe-dd87204c8721","email":"support@moonshadowmobile.com","is_active":true,"is_deleted":false,"name":"Moonshadow Mobile","permissions":[{"action":"modify","action_detail":"modify_customer","permission_id":20,"permission_type_id":2,"target_type":"customer"},{"action":"deactivate","action_detail":"deactivate_customer","permission_id":21,"permission_type_id":3,"target_type":"customer"},{"action":"activate","action_detail":"activate_customer","permission_id":22,"permission_type_id":4,"target_type":"customer"},{"action":"delete","action_detail":"delete_customer","permission_id":23,"permission_type_id":5,"target_type":"customer"},{"action":"read","action_detail":"get_customer","permission_id":24,"permission_type_id":6,"target_type":"customer"},{"action":"read customer","action_detail":"get_customer_users","permission_id":25,"permission_type_id":16,"target_type":"customer"},{"action":"read customer","action_detail":"get_customer_devices","permission_id":26,"permission_type_id":23,"target_type":"customer"},{"action":"read customer","action_detail":"get_customer_keys","permission_id":27,"permission_type_id":37,"target_type":"customer"},{"action":"read","action_detail":"get_customer_datasource_schemas","permission_id":28,"permission_type_id":47,"qualifier":"schemas","target_type":"customer"},{"action":"read customer","action_detail":"get_customer_datasources","permission_id":29,"permission_type_id":61,"target_type":"customer"},{"action":"read customer","action_detail":"get_customer_device_templates","permission_id":30,"permission_type_id":68,"target_type":"customer"},{"action":"read customer","action_detail":"get_customer_device_collections","permission_id":31,"permission_type_id":77,"target_type":"customer"},{"action":"read customer","action_detail":"get_customer_permission_sets","permission_id":32,"permission_type_id":87,"target_type":"customer"},{"action":"read","action_detail":"get_generic_permissions","permission_id":33,"permission_type_id":98,"qualifier":"permissions","target_type":"customer"},{"action":"read customer","action_detail":"get_customer_abstract_permissions","permission_id":34,"permission_type_id":99,"target_type":"customer"}]}}}
GET /customer/{customer_id}/datasources

Route parameters

customer_id uuid

  • Customer ID for which to list datasources

Query string parameters

with_permissions boolean

  • Include or omit the permission space for this object

Description

This API allows retrieval of the datasources for a particular customer. It is not possible to request datasources for a customer other than the one that owns the API key being used in the request.

Response definition

datasources array [datasource :: object]

  • The datasources that belong to this customer
  • See Get Datasource for response definition

Examples

Request

GET /customer/13855d51-5922-4a00-a9fe-dd87204c8721/datasources?with_permissions=false

Response

{"result":{"status":"ok","customer_id":"66f43d09-48db-4a59-be6a-c22dd87e4308","datasources":[{"datasource_id":"43ef7f0a-b29c-49a2-9819-8beebb5ce468","customer_id":"66f43d09-48db-4a59-be6a-c22dd87e4308","name":"yellAtMe!","datasource_schema_id":"ba49ae6c-d50d-4340-91b7-3487f74fe25b","engine_type_id":2,"engine_type":"ephemeris","engine_version":"1.0","is_active":false,"is_deleted":false,"is_instantiated":false,"instantiated":"","created":"2017-07-11 16:25:47.866161"},{"datasource_id":"6fdcc4eb-5228-498c-a121-446641ecf3da","customer_id":"66f43d09-48db-4a59-be6a-c22dd87e4308","name":"genericData","datasource_schema_id":"035c401e-fdd1-4dbe-9b76-381cd16729e4","engine_type_id":2,"engine_type":"ephemeris","engine_version":"1.0","is_active":true,"is_deleted":false,"is_instantiated":true,"instantiated":"2017-07-12 14:22:35.644141","created":"2017-07-12 14:22:26.934282"},{"datasource_id":"a6d9eb48-539c-4327-8232-d4aef688475b","customer_id":"66f43d09-48db-4a59-be6a-c22dd87e4308","name":"justForYouPatrick","datasource_schema_id":"035c401e-fdd1-4dbe-9b76-381cd16729e4","engine_type_id":2,"engine_type":"ephemeris","engine_version":"1.0","is_active":true,"is_deleted":false,"is_instantiated":true,"instantiated":"2017-07-19 11:22:07.15834","created":"2017-07-19 11:21:56.689481"}]}}
GET /customer/{customer_id}/keys

Route parameters

customer_id string

  • ID of customer to request keys for

Query string parameters

with_permissions boolean

  • Include or omit the permission space for the objects returned

Description

This API allows retrieval of the keys for a particular customer. It is not possible to request keys for a customer other than the one that owns the API key being used in the request.

Response definition

keys array [key :: object]

  • The keys that belong to users and devices within this customer
  • See Get Key for response definition

Examples

Request

GET /customer/13855d51-5922-4a00-a9fe-dd87204c8721/keys?with_permissions=true

Response

{"status":"ok","data":{"customer_id":"13855d51-5922-4a00-a9fe-dd87204c8721","keys":[{"created":"2016-04-19 19:35:21.441437","cross_customer_enabled":true,"is_active":true,"is_admin":true,"is_deleted":false,"key_id":"srsnqrwvxwzsxkprsrpnnlnvvonustol","object_id":"0f40a138-9a88-4bde-b5aa-1a72351f1ed5","owner_customer_id":"13855d51-5922-4a00-a9fe-dd87204c8721","owner_id":"0e6a0891-38b5-40b4-b426-b3a5f0bf04d8","owner_type":"D","permissions":[{"action":"deactivate","action_detail":"deactivate_key","permission_id":196,"permission_type_id":26,"target_type":"api key"},{"action":"activate","action_detail":"activate_key","permission_id":197,"permission_type_id":27,"target_type":"api key"},{"action":"delete","action_detail":"delete_key","permission_id":198,"permission_type_id":28,"target_type":"api key"},{"action":"grant","action_detail":"grant_key_permissions","permission_id":199,"permission_type_id":29,"qualifier":"permissions","target_type":"api key"},{"action":"revoke","action_detail":"revoke_key_permissions","permission_id":200,"permission_type_id":30,"qualifier":"permissions","target_type":"api key"},{"action":"add","action_detail":"add_permission_sets_to_key","permission_id":201,"permission_type_id":31,"qualifier":"permission sets","target_type":"api key"},{"action":"remove","action_detail":"remove_permission_sets_from_key","permission_id":202,"permission_type_id":32,"qualifier":"permission sets","target_type":"api key"},{"action":"upgrade","action_detail":"enable_key_cross_customer","permission_id":203,"permission_type_id":34,"target_type":"api key"},{"action":"downgrade","action_detail":"disable_key_cross_customer","permission_id":204,"permission_type_id":35,"target_type":"api key"},{"action":"read","action_detail":"get_key","permission_id":205,"permission_type_id":36,"target_type":"api key"},{"action":"read","action_detail":"get_key_shared_secret","permission_id":206,"permission_type_id":103,"target_type":"api key"}]}]}}
GET /customer/{customer_id}/users

Route parameters

customer_id string

  • Customer id to request users from

Query string parameters

with_permissions boolean

  • Include or omit the permission space for this object

Description

This API allows retrieval of the users for a particular customer. It is not possible to request users for a customer other than the one that owns the API key being used in the request.

Response definition

users array [user :: object]

  • The users that belong to this customer
  • See Get User for response definition

Examples

Request

GET /customer/13855d51-5922-4a00-a9fe-dd87204c8721/users?with_permissions=true

Response

{"status":"ok","data":{"users":[{"created":"2016-04-19 19:35:21.441437","customer_id":"13855d51-5922-4a00-a9fe-dd87204c8721","email":"support@moonshadowmobile.com","is_active":true,"is_deleted":false,"is_superuser":true,"name":"admin_user","permissions":[{"action":"modify","action_detail":"modify_user","permission_id":129,"permission_type_id":11,"target_type":"user"},{"action":"deactivate","action_detail":"deactivate_user","permission_id":130,"permission_type_id":12,"target_type":"user"},{"action":"activate","action_detail":"activate_user","permission_id":131,"permission_type_id":13,"target_type":"user"},{"action":"delete","action_detail":"delete_user","permission_id":132,"permission_type_id":14,"target_type":"user"},{"action":"read","action_detail":"get_user","permission_id":133,"permission_type_id":15,"target_type":"user"},{"action":"read user","action_detail":"get_user_keys","permission_id":134,"permission_type_id":39,"target_type":"user"},{"action":"read","action_detail":"get_user_datasource_schemas","permission_id":135,"permission_type_id":48,"qualifier":"schemas","target_type":"user"},{"action":"read user","action_detail":"get_user_datasources","permission_id":136,"permission_type_id":63,"target_type":"user"}],"secret_token":"uyzkturosqpoltymqwzzznqsqlwqoolo","user_id":"967119b2-0e68-4b41-adaf-a35aa5b44a81"}]}}
PUT /customer/{customer_id}

Route parameters

customer_id string

  • Customer id to update

Body parameters

name string

  • The name to give the customer
  • Must be globally unique

email string

  • The primary contact email for the customer

Description

This provides a mechanism for certain parameters of a customer to be modified, provided that the requester has object permissions to do so.

Name conflicts

Customer names are unique across the system. Attempts to modify a customer that would result in a conflict will return an error.

Response definition

customer_id uuid

  • The unique identifier for this customer

name string

  • The name of the customer

email email

  • The primary email address for this customer

is_active boolean

  • Whether or not this customer is active and usable

Examples

Request

PUT /customer/2b0338e6-acd1-4c51-bf02-95cacc34cdcf

Body

{"data":{"name": "newname", "email": "test@hello.com"}}

Response

{"status":"ok", "data":{"customer": {"customer_id": "2b0338e6-acd1-4c51-bf02-95cacc34cdcf","name": "newname","email": "test@hello.com","is_active": true}}}

Datasource

Overview

A datasource is analagous to a table in other databases. It is a collection of columns of specific types along with advanced options pertaining to how the datasource stores data. Data is stored according to the type and attribute definitions in each column.

Available APIs

GET /datasource/{datasource_id}

Route parameters

datasource_id string

Query string parameters

with_permissions boolean

  • Include or omit the permission space for this object
  • Default value: false

Description

This API allows for the retrieval of metadata describing a previously created datasource.

Response definition

datasource_id

  • The unique identifier for the datasource.

datasource_schema_id uuid

  • The unique identifier for the schema used to create the datasource.

customer_id uuid

  • The unique identifier for the customer that owns this datasource.

engine_type string

  • The engine storage backing the datasource.

engine_type_id integer

  • The internal identifier for the engine_type.

engine_version string

  • The major version of the engine backing the datasource.

name string

  • The name given to this datasource. Must be unique.

permissions array [permission :: object]

  • The set of object permissions that apply to this datasource.

instantiated timestamp

  • The timestamp at which instantiation of this datasource occurred.

is_active boolean

  • Whether or not this object is active.

is_deleted boolean

  • Whether or not this object is deleted.

is_instantiated boolean

  • Whether or not this datasource has been instantiated.

Examples

Request

GET /datasource/6edf5b5f-d438-4796-84c8-cf600f036424?with_permissions=true

Response

{"status":"ok","data":{"datasource":{"created":"2016-08-19 20:53:54.666818","customer_id":"13855d51-5922-4a00-a9fe-dd87204c8721","datasource_id":"6edf5b5f-d438-4796-84c8-cf600f036424","datasource_schema_id":"250a5770-b2b4-4d4a-80bc-27e6f2748a6f","engine_type":"ephemeris","engine_type_id":2,"engine_version":"1.0","instantiated":"","is_active":true,"is_deleted":false,"is_instantiated":false,"name":"Datasource 1","permissions":[{"action":"modify","action_detail":"modify_datasource","permission_id":61339,"permission_type_id":51,"target_type":"datasource"},{"action":"modify","action_detail":"modify_schema_for_datasource","permission_id":61340,"permission_type_id":52,"target_type":"datasource"},{"action":"deactivate","action_detail":"deactivate_datasource","permission_id":61341,"permission_type_id":53,"target_type":"datasource"},{"action":"activate","action_detail":"activate_datasource","permission_id":61342,"permission_type_id":54,"target_type":"datasource"},{"action":"delete","action_detail":"delete_datasource","permission_id":61343,"permission_type_id":55,"target_type":"datasource"},{"action":"unlink","action_detail":"unlink_schema_from_datasource","permission_id":61344,"permission_type_id":56,"target_type":"datasource"},{"action":"purge","action_detail":"purge_datasource","permission_id":61345,"permission_type_id":57,"target_type":"datasource"},{"action":"instantiate","action_detail":"instantiate_datasource","permission_id":61346,"permission_type_id":58,"target_type":"datasource"},{"action":"read","action_detail":"get_datasource","permission_id":61347,"permission_type_id":59,"target_type":"datasource"},{"action":"read","action_detail":"get_datasource_data_nodes","permission_id":61348,"permission_type_id":60,"target_type":"datasource"},{"action":"append data","action_detail":"ingest_data","permission_id":61349,"permission_type_id":88,"target_type":"datasource"},{"action":"append data","action_detail":"ingest_batch","permission_id":61350,"permission_type_id":90,"target_type":"datasource"},{"action":"delete data","action_detail":"delete_range","permission_id":61351,"permission_type_id":91,"qualifier":"timestamp range","target_type":"datasource"},{"action":"read raw","action_detail":"query_raw","permission_id":61352,"permission_type_id":92,"qualifier":"raw","target_type":"datasource"},{"action":"read rollup","action_detail":"query_rollup","permission_id":61353,"permission_type_id":93,"qualifier":"rollup","target_type":"datasource"},{"action":"read topn","action_detail":"query_topn","permission_id":61354,"permission_type_id":94,"qualifier":"topn","target_type":"datasource"},{"action":"read groupby","action_detail":"query_groupbys","permission_id":61355,"permission_type_id":95,"qualifier":"groupby","target_type":"datasource"}]}}}
PUT /datasource/{datasource_id}/instantiate

Route parameters

datasource_id string

Description

This API prepares a datasource for use by push and analysis APIs. Once instantiated successfully, the datasource is ready for use.

Examples

Request

PUT /datasource/6edf5b5f-d438-4796-84c8-cf600f036424/instantiate

Response

{"status":"ok","data":{}}

The relationship between schemas and datasources

As mentioned in the Datasource schema documentation, a datasource schema is a definition that describes the structure of a datasource. A single datasource schema may be used to create multiple datasources. This is useful for instances where multiple datasources with the same structure are desired.

Once a datasource has been created from a schema, the schema is permanently associated with that datasource and can no longer be directly modified. As described previously, a schema may be linked in this way to multiple datasources.

What is instantiation?

Once a schema has been created, and one or more datasources created using that schema, the datasource must be instantiated before use. Prior to instantiation, a datasource is in an intermediate state where it is not suitable for use. In order to push data or perform analysis on a datasource, it must be instantiated into the engine cluster. In most cases, this is done with a single call to the Instantiate datasource API route. Once successful, the datasource is fully realized and ready for use.

A full example

In this example, we will issue four API calls to create a datasource schema, a datasource from that schema, and finally instantiate this datasource and verify that it is ready for use.

Note that in the case of creating the schema and datasource, the return response includes object permission ids that can then be assigned to API keys to permit access.

Creating the schema

Since schemas are created by users or devices, we will create a simple schema under a pre-created user with the id 967119b2-0e68-4b41-adaf-a35aa5b44a81:

POST /v1/user/967119b2-0e68-4b41-adaf-a35aa5b44a81/datasource_schemas

Request body:

{"data":{"name":"Datasource Schema 1","schema_data":{"key":[{"type":"uuid","column_id":"id"}],"static_columns":[{"type":"selector","column_id":"model","attributes":{"values":["Phantom","Matrice100","AirborneNight","AirborneCargo","Hydrofoil","JumpingNight","JumpingRace","MatternetONE","EVOLUTION3"]}},{"type":"selector","column_id":"make","attributes":{"values":["DajiangInnovation","ParrotEPA","Matternet","Skycatch"]}}],"time_series_columns":[{"type":"integer","column_id":"fuel","attributes":{"min_value":0,"max_value":100000}},{"type":"selector","column_id":"charging","attributes":{"values":["Charging","Discharging"]}},{"type":"geographic_point","column_id":"point","attributes":{"latitude":"lat","longitude":"long"}}]}}}

Response body:

{"status":"ok","data":{"datasource_schema":{"customer_id":"13855d51-5922-4a00-a9fe-dd87204c8721","datasource_count":0,"datasource_schema_id":"250a5770-b2b4-4d4a-80bc-27e6f2748a6f","engine_type":"ephemeris","engine_type_id":2,"engine_version":"1.0","name":"Datasource Schema 1","owner_id":"967119b2-0e68-4b41-adaf-a35aa5b44a81","owner_type":"U","owner_type_id":4,"permissions":[{"action":"modify","action_detail":"modify_datasource_schema","permission_id":61333,"permission_type_id":41,"target_type":"datasource schema"},{"action":"delete","action_detail":"delete_datasource_schema","permission_id":61334,"permission_type_id":42,"target_type":"datasource schema"},{"action":"protect","action_detail":"protect_datasource_schema","permission_id":61335,"permission_type_id":43,"target_type":"datasource schema"},{"action":"unprotect","action_detail":"unprotect_datasource_schema","permission_id":61336,"permission_type_id":44,"target_type":"datasource schema"},{"action":"read","action_detail":"get_schema_datasources","permission_id":61337,"permission_type_id":45,"target_type":"datasource schema"},{"action":"read","action_detail":"get_datasource_schema","permission_id":61338,"permission_type_id":46,"target_type":"datasource schema"}],"schema_data":{"key":[{"column_id":"id","type":"uuid"}],"static_columns":[{"attributes":{"values":["Phantom","Matrice100","AirborneNight","AirborneCargo","Hydrofoil","JumpingNight","JumpingRace","MatternetONE","EVOLUTION3"]},"column_id":"model","type":"selector"},{"attributes":{"values":["DajiangInnovation","ParrotEPA","Matternet","Skycatch"]},"column_id":"make","type":"selector"}],"time_series_columns":[{"attributes":{"max_value":100000,"min_value":0},"column_id":"fuel","type":"integer"},{"attributes":{"values":["Charging","Discharging"]},"column_id":"charging","type":"selector"},{"column_id":"point","type":"geographic_point"}]}}}}

Creating the datasource

Now that a schema exists, a datasource can be created under the control of the customer for that schema. Here, we are using the customer_id of the user that was used to create the schema:

POST /v1/customer/13855d51-5922-4a00-a9fe-dd87204c8721/datasources

Request body:

{"data":{"datasource_schema_id":"250a5770-b2b4-4d4a-80bc-27e6f2748a6f","name":"Datasource 1"}}

Response body:

{"status":"ok","data":{"datasource":{"customer_id":"13855d51-5922-4a00-a9fe-dd87204c8721","datasource_id":"6edf5b5f-d438-4796-84c8-cf600f036424","datasource_schema_id":"250a5770-b2b4-4d4a-80bc-27e6f2748a6f","engine_type":"ephemeris","engine_type_id":2,"engine_version":"1.0","name":"Datasource 1","permissions":[{"action":"modify","action_detail":"modify_datasource","permission_id":61339,"permission_type_id":51,"target_type":"datasource"},{"action":"modify","action_detail":"modify_schema_for_datasource","permission_id":61340,"permission_type_id":52,"target_type":"datasource"},{"action":"deactivate","action_detail":"deactivate_datasource","permission_id":61341,"permission_type_id":53,"target_type":"datasource"},{"action":"activate","action_detail":"activate_datasource","permission_id":61342,"permission_type_id":54,"target_type":"datasource"},{"action":"delete","action_detail":"delete_datasource","permission_id":61343,"permission_type_id":55,"target_type":"datasource"},{"action":"unlink","action_detail":"unlink_schema_from_datasource","permission_id":61344,"permission_type_id":56,"target_type":"datasource"},{"action":"purge","action_detail":"purge_datasource","permission_id":61345,"permission_type_id":57,"target_type":"datasource"},{"action":"instantiate","action_detail":"instantiate_datasource","permission_id":61346,"permission_type_id":58,"target_type":"datasource"},{"action":"read","action_detail":"get_datasource","permission_id":61347,"permission_type_id":59,"target_type":"datasource"},{"action":"read","action_detail":"get_datasource_data_nodes","permission_id":61348,"permission_type_id":60,"target_type":"datasource"},{"action":"append data","action_detail":"ingest_data","permission_id":61349,"permission_type_id":88,"target_type":"datasource"},{"action":"append data","action_detail":"ingest_batch","permission_id":61350,"permission_type_id":90,"target_type":"datasource"},{"action":"delete data","action_detail":"delete_range","permission_id":61351,"permission_type_id":91,"qualifier":"timestamp range","target_type":"datasource"},{"action":"read raw","action_detail":"query_raw","permission_id":61352,"permission_type_id":92,"qualifier":"raw","target_type":"datasource"},{"action":"read rollup","action_detail":"query_rollup","permission_id":61353,"permission_type_id":93,"qualifier":"rollup","target_type":"datasource"},{"action":"read topn","action_detail":"query_topn","permission_id":61354,"permission_type_id":94,"qualifier":"topn","target_type":"datasource"},{"action":"read groupby","action_detail":"query_groupbys","permission_id":61355,"permission_type_id":95,"qualifier":"groupby","target_type":"datasource"}]}}}

Instantiating the datasource

With the framework of the datasource ready, instantiation will make the datasource ready to accept requests:

PUT /v1/datasource/6edf5b5f-d438-4796-84c8-cf600f036424/instantiate

Request body:

{"data":{}}

Response body:

{"status":"ok","data":{}}

A sample query to demonstrate readiness for use

While any of the analysis and push APIs can be used, here we choose to use get_event_time_range to show that our datasource is indeed reachable and contains no data:

POST /v1/datasource/6edf5b5f-d438-4796-84c8-cf600f036424/analyze

Request body:

{"data":{"method":"get_event_time_range"}}

Response body:

{"status":"ok","data":{"datasource_id":"6edf5b5f-d438-4796-84c8-cf600f036424","min":0,"max":0,"time_in_usec":29}}

What can be done with an instantiated datasource

Push APIs

Insertion of data into an instantiated datasource is done with the Push APIs. At present, only real-time streaming APIs are supported using the add_static_data and add_time_series_data methods accessed via the API.

Analysis APIs

Queries on previously inserted data, i.e. image tiles, CSV/JSON event exports, GeoJSON, binned exports, etc. can be issued to an instantiated datasource. As is to be expected, analysis queries require that data exist in the datasource in order to return any useful information.

Null and undefined values

DB4IoT has two distinct and subtly different types of what a SQL database would call a "NULL" value:

  • null: An explicitly provided empty value. This can be conceptualized as the "empty" value, which has an actual representation in the data.
  • undefined: An internal value that indicates a complete absence of information.

Reasoning and use-case

As an example to aid in why this separation exists, take for instance a vehicle engine temperature sensor that is recording temperature readings. A sample of such data as recorded directly from the device might look like the following:

"device_id","event_timestamp","temperature"
123, 1, 195
123, 2, 200
123, 3, 9999999
123, 4, 215
	

Notice at time 3, the temperature has an erroneous value of 9999999. This is likely outside of the range for this numeric column (as specified in the schema), in addition to being bogus and useless. In this case, when inserting this data one can use the explicit JSON null for this timestamp to indicate that this sensor collected a false reading that should be disregarded.

By putting this logic in code that sends data to DB4IoT, later analysis can reveal the severity and frequency of malfunctioning equipment sensors that would otherwise be very difficult to detect if such a value were simply discarded and no information were recorded.

Now, let us consider what would happen if we were to not send the explicit "null" for event_timestamp 3. In this case, the internal database engine would view the value of the temperature column at time 3 to be "undefined", since there is absolutely no information about what occurred at this time.

Overview

Datasource "links" are a mechanism for giving more than one customer access to an individual datasource.

Under ordinary circumstances, datasources are created by, and for the benefit of, a single customer. However, it may be desirable for more than one customer to access a datasource; for one thing, this means that only one physical datasource is needed, whereas without sharing, physical copies of the datasource would be required, one for each customer.

The general use case for sharing datasources is:

  • More than one customer requires access to a single datasource
  • Each customer expects to see the same data
  • Only one customer will be pushing data to the datasource; this will be the customer that creates the datasource
  • Only one customer will be performing administrative tasks on the datasource; again, this will be the customer that creates the datasource
  • All other customers sharing the datasource will have read-only access to it, and find that acceptable

We will speak here of "owner customer" and "target customer." The owner customer is the customer that created the datasource. A target customer is some customer with whom the owner customer would like to share a datasource.

A brief example of the lifecyle of a datasource link:

  1. A datasource schema is created by customer A
  2. Customer A creates datasource Z from the datasource schema
  3. Customer A (owner) creates a datasource link to share datasource Z with customer B (target).
  4. Customer B now has read permissions on datasource Z (and its schema), but cannot push data to the datasource, nor perform any administrative tasks on it (or its schema)
  5. Customer B needs to know nothing about the datasource link; from customer B's perspective, they simply have read-only access to a datasource created by some other customer
  6. Meanwhile, customer A can push data to datasource Z, change it (and its schema) and generally manage it as needed
  7. At some point, customer A may wish to deny customer B access to datasource Z, either permanently or temporarily. This can be done either by deactivating the datasource link, or by deleting it permanently.
  8. Unused or obsolete datasource links may be deleted permanantly as well, just to reduce clutter. Datasources shared through datasource links are never affected by operations on the links.

There may be only one datasource link per datasource/target customer pair. In the example above, only one datasource link may exist to grant access to datasource Z to customer B. Attempting to create a second link between datasource Z and customer B will generate an error.

Note that datasource links can be created for datasources that have not yet been instantiated. Attempting to access a datasource that has not been instantiated will produce an error; this is also true when access is granted through a datasource link. It is probably good policy to avoid a creating datasource links until the underlying datasource has been instantiated.

Also note that deleting a datasource link removes it permanently. If the sharing relationship established by the deleted link must be reestablished, then a new datasource link must be created.

Available APIs

Datasource Schema

Overview

A datasource schema is similar to a table definition in a traditional database, describing columns, their data types, and various other metadata. Datasource schemas are described in a simple, declarative JSON syntax.

Once used to instantiate a datasource, a datasource schema enters a read-only, protected state. At this time, datasource schemas do not support the analog of ALTER in a traditional SQL database.

In the event that you require a modification to your datasource schema after instantiating one or more datasource(s) from it, you will need to create a new datasource schema with your changes. Then, you can instantiate a new datasource from the new schema. Note that separate datasources must be queried separately. The equivalent of a JOIN is not currently supported.

Available APIs

GET /datasource_schema/{datasource_schema_id}

Route parameters

datasource_schema_id string

Description

This endpoint is used for retreiving a previously created datasource schema.

Response definition

datasource_count integer

  • The number of datasources that have been created from this schema.

datasource_schema_id uuid

  • The unique identifier for this datasource schema.

customer_id uuid

  • The unique identifier for the customer that owns this datasource.

engine_type string

  • The engine storage to be used for datasources created from this schema.

engine_type_id integer

  • The internal identifier for the engine_type to be used for datasources created from this schema.

engine_version string

  • The major version of the engine that backs datasources created from this schema.

name string

  • The name given to this datasource schema. Must be unique.

permissions array [permission :: object]

  • The set of object permissions that apply to this datasource schema.

is_readonly boolean

  • Whether or not this datasource schema can be modified. Once a schema has been used to instantiate a datasource, this is set to true.

owner_type string

  • The type of object that owns this schema. One of 'U' (user) or 'D' (device).

owner_type_id integer

  • The internal identifier for the owner_type of the user or device that owns this datasource schema.

is_deleted boolean

  • Whether or not this object is deleted.

owner_id uuid

  • The unique identifier for the user or device that created this datasource schema.

schema_data object

  • The schema data structure.

Examples

Request

GET /datasource_schema/637ce121-4926-4fbf-9d25-dd5573743c08?with_permissions=true

Response

{"status":"ok","data":{"datasource_schema":{"customer_id":"13855d51-5922-4a00-a9fe-dd87204c8721","datasource_count":0,"datasource_schema_id":"637ce121-4926-4fbf-9d25-dd5573743c08","engine_type":"ephemeris","engine_type_id":2,"engine_version":"1.0","is_deleted":false,"is_readonly":false,"name":"New Datasource Schema","owner_id":"0f267db6-0f9a-4a07-98cd-addf5e834f6a","owner_type":"U","owner_type_id":4,"permissions":[{"action":"modify","action_detail":"modify_datasource_schema","permission_id":98515,"permission_type_id":41,"target_type":"datasource schema"},{"action":"delete","action_detail":"delete_datasource_schema","permission_id":98516,"permission_type_id":42,"target_type":"datasource schema"},{"action":"protect","action_detail":"protect_datasource_schema","permission_id":98517,"permission_type_id":43,"target_type":"datasource schema"},{"action":"unprotect","action_detail":"unprotect_datasource_schema","permission_id":98518,"permission_type_id":44,"target_type":"datasource schema"},{"action":"read","action_detail":"get_schema_datasources","permission_id":98519,"permission_type_id":45,"target_type":"datasource schema"},{"action":"read","action_detail":"get_datasource_schema","permission_id":98520,"permission_type_id":46,"target_type":"datasource schema"}],"schema_data":{"key":[{"column_id":"id","type":"uuid"}],"static_columns":[{"attributes":{"values":["Phantom","Matrice100","AirborneNight","AirborneCargo","Hydrofoil","JumpingNight","JumpingRace","MatternetONE","EVOLUTION3"]},"column_id":"model","type":"selector"},{"attributes":{"values":["DajiangInnovation","ParrotEPA","Matternet","Skycatch"]},"column_id":"make","type":"selector"}],"time_series_columns":[{"attributes":{"max_value":100000,"min_value":0},"column_id":"fuel","type":"integer"},{"attributes":{"values":["Charging","Discharging"]},"column_id":"charging","type":"selector"},{"attributes":{"latitude":"lat","longitude":"long"},"column_id":"point","type":"geographic_point"}]}}}}

Structure

The following is a simple datasource schema describing a fleet of drones and their attributes:

{"key":[{"type":"uuid","column_id":"id"}],"static_columns":[{"type":"selector","column_id":"model","attributes":{"values":["Phantom","Matrice 100","Airborne Night","Airborne Cargo","Hydrofoil","Jumping Night","Jumping Race","Matternet ONE","EVOLUTION 3"]}},{"type":"selector","column_id":"make","attributes":{"values":["Dajiang Innovation","Parrot EPA","Matternet","Skycatch"]}}],"time_series_columns":[{"type":"integer","column_id":"fuel","attributes":{"min_value":0,"max_value":100000}},{"type":"selector","column_id":"charging","attributes":{"values":["Charging","Discharging"]}},{"type":"geographic_point","column_id":"point","attributes":{"latitude":"lat","longitude":"long"}}]}

Refer to the following sections for descriptions of what each piece of this example means.

Columns

Columns describe the structure of the data stored in a datasource. Column definitions have the following structure:

{"type":"","column_id":"","display_name":"","description":"","attributes":{}}

type

This corresponds to one of the supported column data types.

column_id

Analogous to a "column name" in other databases, this is used to identify and reference a column. This will be used when including this column in push or analysis requests. The value provided must be unique within a given datasource schema, including those specified as latitude and longitude column_id aliases within the geographic_point type. The value provided must satisfy the following conditions:

  • Consist only of alphanumeric characters and underscores
  • Begin with a letter

display_name

A plain-text "human friendly" name for the column. The display_name is provided as a convenient label for viewing, and may not be used to reference a column directly in requests of any kind.

description

A plain-text description of the purpose of the column. This is more-or-less like a COMMENT as used in traditional databases. The description may not be used to reference a column directly in requests of any kind.

units

A text string that describes what units values of a column are to be interpreted as. For example, one might specify {...,"units":"meter/second",...} for a column that contains velocity values. See the Math.js units documentation for a full list of supported unit types.

attributes

The attributes section contains data type-specific metadata about the column, such as enumerable values (selector type), numerical ranges (integer type), and more. They provide simple constraints, descriptions, and integrity checks for inserted data. Consult the documentation for specific data types for the spectrum of attribute options available. Note that attributes may be optional for certain types.


Supported Column Data Types

The complete list of supported data types and their options are listed below.

integer

This type is used to represent signed and unsigned integer values.

Available column attributes:
  • min_value

    The minimum integer value to be stored in this column.

  • max_value

    The maximum integer value to be stored in this column.

  • Ranges that most accurately reflect the data will result in optimal efficiency. However, be certain that you account for the immutability of the schema and don't restrict a column that may require a different range in the future.

    Note that due to the immutability of a datasource schema, min_value and max_value may not be modified after instantiation of a datasource!


fixed_point

This type is used to represent signed and unsigned fixed point values.

Available column attributes:
  • min_value

    The minimum integer value to be stored in this column.

  • max_value

    The maximum integer value to be stored in this column.

  • precision

    The maximum precision to be stored. E.g. a precision of 4 could store up to 4 points of decimal precision.

  • Ranges that most accurately reflect the data will result in optimal efficiency. However, be certain that you account for the immutability of the schema and don't restrict a column that may require a different range in the future.

    Note that due to the immutability of a datasource schema, min_value and max_value may not be modified after instantiation of a datasource!


selector

This type is used for storing a set of predefined string values. It is also suitable to describe this as an "enumerated type".

Use cases include: vehicle make, vehicle model, and persisting transient object properies over time.

Available column attributes:
  • values

    An array of string values representing a predefined list of which only one value may be selected at any given time.


timestamp

This type is used for representing temporal integer offsets from an arbitrary point in time. The minimum granularity is currently limited to the nearest second.

Use cases include: storage of arbitrary timestamp offsets from an arbitrary starting point, and storing standard UNIX timestamps.

Available column attributes:
  • time_units_per_second

    The resolution that offset values provided for this column represent. For example, a time_units_per_second value of 60 means that each integer offset from the epoch is 1/60th of a second.

    If unspecified, this attribute defaults to 1, which means that each integer offset value represents one second.

  • epoch

    The starting reference point in time that all offset value provided for this column are relative to. This attribute supports only UTC timestamps.

    If unspecified, this attribute defaults to "1970-01-01T00:00:00Z", which is the UNIX epoch.


date

This type is used for storing dates of the form mm/dd/yyyy, with a minimum resolution of 1 day.

Use cases include: efficient storage of lower granularity temporal data

Available column attributes:
  • None.

geographic_point

This type is used for storing latitude/longitude composite pairs.

The accuracy of coordinates stored varies between 4mm at the equator (thus, any measurement provided will fall within 2mm of the actual value), and improves as the latitude of the measurement moves toward either pole.

Use cases include: static object location (such as an immobile installation), tracking of objects over time geospatially (such as vehicles).

Available column attributes:
  • latitude

    A column_id to use as an alias for the latitudinal component of the geographic_point. The alias provided must be unique across all column_id declarations in the schema.

    If not provided, the latitudinal component can be accessed via the column_id of the parent geographic_point and _latitude as a single string. E.g. if the outer geographic_point had an id of "point", then the syntax would be point_latitude.

  • longitude

    A column_id to use as an alias for the longitudinal component of the geographic_point. The alias provided must be unique across all column_id declarations in the schema.

    If not provided, the longitudinal component can be accessed via the column_id of the parent geographic_point and _longitude as a single string. E.g. if the outer geographic_point had an id of "point", then the syntax would be point_longitude.


latitude

This type is used for storing the latitude portion of a geospatial coordinate. This has the format of a fixed point value with up to 7 points of precision, e.g. 40.4469471.

Use cases include: analysis of groups of objects at specific latitudinal ranges.

Available column attributes:
  • None.

longitude

This type is used for storing the longitude portion of a geospatial coordinate. This has the format of a fixed point value with up to 7 points of precision, e.g. -100.7226563.

Use cases include: analysis of groups of objects at specific longitudinal ranges.

Available column attributes:
  • None.

varchar

A standard UTF-8 encoded string type.

This type is used for storing arbitrary strings.

Use cases include: free-form text entry fields, arbitrary text, otherwise unencodable values (such as binary).

Use selector when possible!

When the permutations of the set of strings you intend to store is known and static, the selector will yield vastly superior storage efficiency. Only use varchar if the data to be stored cannot be determined ahead of time.

Available column attributes:
  • length

    The maximum length of the strings to be stored in this column.


uuid

This type is used for storing any UUID RFC 4122 variant.

Use cases include: object identifiers, networked device identifiers.

Available column attributes:
  • None.

Datasource schema properties

key

Roughly analogous to a primary key in a traditional database, this is an array of one or more columns that taken together create a unique composite key.

Any combination of the following types (and their associated attributes) are permitted as key columns:

  • integer
  • varchar
  • selector
  • timestamp
  • date
  • uuid
  • geographic_point
  • latitude
  • longitude

static_columns

Columns specified in this array contain values that, for any given event_timestamp, have the same value.

To illustrate the concept of a static column, suppose we have an integer column with column_id "state" specified in static_columns. At event_timestamp of 42 we set the value of "state" to the value 5. For all values of event_timestamp from 1 to the end of time, the value of "state" is now 5.

Suppose "state" at event_timestamp of 25 is set to 10. As before, we've now essentially "rewritten history" and made 10 the value for all time.

The best use case for static_columns is for seldomly-changing or unchanging properties that crucially, do not need their state changes tracked throughout time. Things like the make and model of a vehicle would be good candidates for static_columns, as would a geographic_point of a normally static installation that on rare occasion, will be moved to a different location.


time_series_columns

Columns specified in this array may contain different values for any given event_timestamp.

Use time_series_columns for data that should have changes to that data tracked over time.

The obvious use of columns in this category is for time series analysis. For example, updating the latitude and longitude of objects over time using a geographic_point column allows for visualization and statistical analysis for any value of event_timestamp desired.


Device

Overview

To facilitate analytics, all devices are identified by a UUID assigned to them at creation time. If you choose to distinguish between different devices within your data (such as by providing a "device_id" dimension in your datasource schema) instead of at the DB4IoT Administrative API level, you can treat the set of data as belonging to a single "superdevice" for purposes of pushing data. In doing this, you lose the ability to manage your individual physical devices via the API. However, it allows you to push your entire device fleet's data as a single entity from the perspective of the API.

We recommend that you create a single device (with accompanying API key/shared secret) for each physical device that collects data. This allows for maximum control over the behavior of individual devices, such as the ability to deactivate compromised devices as well as manage their access to your datasources.

Whether you follow this recommendation or use the "superdevice" pattern described above, your billing will be exactly the same.

Available APIs

PUT /device/{device_id}/activate

Route parameters

device_id string

  • Device id to mark activated

Description

This API allows for devices to be marked as activated. Newly created devices already active. The device can be deactivated at any time, which suspends the ability for that device to interact with the system.

Examples

Request

PUT /device/ff61ac8b-1fda-4f43-928d-79790b7791fd/activate

Response

{"status":"ok", "data":{}}
POST /device/{device_id}/datasource_schemas

Route parameters

device_id string

  • Device id to use as the owner for this datasource schema

Body parameters

name string

  • The name to give the datasource_schema
  • Must be unique within the customer

engine_type string

  • The processing engine this schema is for, currently only "ephemeris"

schema_data object

  • The valid JSON schema definition for the selected engine_type

Description

This endpoint is used for creating datasource schemas with device owners. Note that users may also create datasource schemas through Create Datasource Schema (User owner).

Response definition

customer_id uuid

  • The unique identifier for the customer that owns this datasource schema

owner_id uuid

  • The unique identifier for the device that owns this datasource_schema

owner_type string

  • Always 'D' (device)

owner_type_id int

  • The identifier for the owner_type of this datasource schema

datasource_schema_id uuid

  • The unique identifier for this datasource_schema

name string

  • The name of the datasource_schema

schema_data object

  • A JSON object that defines the datasource schema as it will be applied to the given engine_type

engine_type string

  • The name of the engine that this datasource schema applies to

engine_type_id int

  • The identifier for the engine_type of this datasource schema

permissions array [permission :: object]

  • The set of object permissions that apply to this datasource_schema
  • See Keys and Permissions for response definition

Examples

Request

POST /device/394e749a-8fcf-4b2f-b2e7-99bc3bd03176/datasource_schemas

Body

{"data":{"name": "Datasource Schema 2", "customer_id": "28fbe0a9-bb7f-4935-8e86-4e75db35bd6f","schema_data":{"key":[{"type":"uuid","column_id":"id"}],"static_columns":[{"type":"selector","column_id":"model","attributes":{"values":["Phantom","Matrice100","AirborneNight","AirborneCargo","Hydrofoil","JumpingNight","JumpingRace","MatternetONE","EVOLUTION3"]}},{"type":"selector","column_id":"make","attributes":{"values":["DajiangInnovation","ParrotEPA","Matternet","Skycatch"]}}],"time_series_columns":[{"type":"integer","column_id":"fuel","attributes":{"min_value":0,"max_value":100000}},{"type":"selector","column_id":"charging","attributes":{"values":["Charging","Discharging"]}},{"type":"geographic_point","column_id":"point","attributes":{"latitude":"lat","longitude":"long"}}]}}}

Response

{"status":"ok","data":{"datasource_schema":{"customer_id":"fcd63a01-953d-4fb7-8de0-1ade381ed010","engine_type":"ephemeris","engine_type_id":"2","datasource_schema_id":"51258f04-e29e-4e93-88c1-16de324e259d","name":"Datasource Schema 2","owner_id":"394e749a-8fcf-4b2f-b2e7-99bc3bd03176","owner_type":"D","owner_type_id":"4","permissions":[{"action":"modify","action_detail":"modify_datasource_schema","permission_id":31035,"permission_type_id":37,"target_type":"datasource schema"},{"action":"delete","action_detail":"delete_datasource_schema","permission_id":31036,"permission_type_id":38,"target_type":"datasource schema"},{"action":"read","action_detail":"get_datasource_schema","permission_id":31037,"permission_type_id":39,"target_type":"datasource schema"}],"schema_data":{"key":[{"type":"uuid","column_id":"id"}],"static_columns":[{"type":"selector","column_id":"model","attributes":{"values":["Phantom","Matrice100","AirborneNight","AirborneCargo","Hydrofoil","JumpingNight","JumpingRace","MatternetONE","EVOLUTION3"]}},{"type":"selector","column_id":"make","attributes":{"values":["DajiangInnovation","ParrotEPA","Matternet","Skycatch"]}}],"time_series_columns":[{"type":"integer","column_id":"fuel","attributes":{"min_value":0,"max_value":100000}},{"type":"selector","column_id":"charging","attributes":{"values":["Charging","Discharging"]}},{"type":"geographic_point","column_id":"point","attributes":{"latitude":"lat","longitude":"long"}}]}}}}
POST /device/{device_id}/keys

Route parameters

device_id string

  • The id of the device to create the key for

Description

This endpoint is used for creating a key and attaching it to a device.

Response definition

key_id string

  • The identifier for this key used in API authentication

object_id uuid

  • The unique identifier for this object

owner_id uuid

  • The unique identifier for the device that owns this key

owner_type string

  • For this call, always 'D' (device)

permissions array [permission :: object]

  • The set of object permissions that apply to this key
  • See Keys and Permissions for response definition

Examples

Request

POST /device/3a4bf4be-5cc2-4a88-b2a6-fdf888b6a007/keys

Body

{"data":{"name":"New Device Key"}}

Response

{"status":"ok","data":{"key":{"customer_id":"13855d51-5922-4a00-a9fe-dd87204c8721","key_id":"xovruxnwxltqpnknyxmnxkvooslrmylt","object_id":"70140f8d-912a-4952-90d8-d380bc80578f","owner_id":"3a4bf4be-5cc2-4a88-b2a6-fdf888b6a007","owner_type":"D","owner_type_id":8,"permissions":[{"action":"deactivate","action_detail":"deactivate_key","permission_id":98493,"permission_type_id":26,"target_type":"api key"},{"action":"activate","action_detail":"activate_key","permission_id":98494,"permission_type_id":27,"target_type":"api key"},{"action":"delete","action_detail":"delete_key","permission_id":98495,"permission_type_id":28,"target_type":"api key"},{"action":"grant","action_detail":"grant_key_permissions","permission_id":98496,"permission_type_id":29,"qualifier":"permissions","target_type":"api key"},{"action":"revoke","action_detail":"revoke_key_permissions","permission_id":98497,"permission_type_id":30,"qualifier":"permissions","target_type":"api key"},{"action":"add","action_detail":"add_permission_sets_to_key","permission_id":98498,"permission_type_id":31,"qualifier":"permission sets","target_type":"api key"},{"action":"remove","action_detail":"remove_permission_sets_from_key","permission_id":98499,"permission_type_id":32,"qualifier":"permission sets","target_type":"api key"},{"action":"upgrade","action_detail":"enable_key_cross_customer","permission_id":98500,"permission_type_id":34,"target_type":"api key"},{"action":"downgrade","action_detail":"disable_key_cross_customer","permission_id":98501,"permission_type_id":35,"target_type":"api key"},{"action":"read","action_detail":"get_key","permission_id":98502,"permission_type_id":36,"target_type":"api key"},{"action":"read","action_detail":"get_key_shared_secret","permission_id":98503,"permission_type_id":103,"target_type":"api key"}]}}}
PUT /device/{device_id}/deactivate

Route parameters

device_id string

  • Device id to mark deactivated

Description

This API allows for devices to be marked as deactivated. The device may no longer make API requests or otherwise interact with the system. The device can be reactivated at any time.

Examples

Request

PUT /device/ff61ac8b-1fda-4f43-928d-79790b7791fd/deactivate

Response

{"status":"ok", "data":{}}
DELETE /device/{device_id}

Route parameters

device_id string

  • Device id to mark deleted

Description

This API allows for devices to be marked as deleted. The device can no longer be modified, and any keys it has been assigned will cease to function. Deleted devices are retained in the system for record-keeping purposes.

Examples

Request

DELETE /device/16628a92-5693-49f3-ad92-56261f20f46d

Response

{"status":"ok", "data":{}}
GET /device/{device_id}

Route parameters

device_id string

  • Device id to retrieve

Query string parameters

with_permissions boolean

  • Include or omit the permission space for this object

Description

This command returns information about a device, provided that the requester has object permissions to view this information. If "with_permissions" is true, the space of object permissions that apply to the device will be returned as well.

Response definition

device_id uuid

  • The unique identifier for this device

name string

  • The name of the device

customer_id uuid

  • The unique identifier for the customer that owns this device

created timestamp

  • An ISO 8601 timestamp for when the device was created

is_active boolean

  • Whether or not this device is active and usable

is_deleted boolean

  • Whether or not this device is deleted and no longer valid

permissions array [permission :: object]

  • The set of object permissions that apply to this device
  • See Keys and Permissions for response definition

Examples

Request

GET /v1/device/3a4bf4be-5cc2-4a88-b2a6-fdf888b6a007with_permissions=true

Response

{"status":"ok","data":{"device":{"created":"2016-12-02 20:21:49.772695","customer_id":"13855d51-5922-4a00-a9fe-dd87204c8721","device_id":"3a4bf4be-5cc2-4a88-b2a6-fdf888b6a007","is_active":true,"is_deleted":false,"name":"new.device","permissions":[{"action":"modify","action_detail":"modify_device","permission_id":98485,"permission_type_id":18,"target_type":"device"},{"action":"deactivate","action_detail":"deactivate_device","permission_id":98486,"permission_type_id":19,"target_type":"device"},{"action":"activate","action_detail":"activate_device","permission_id":98487,"permission_type_id":20,"target_type":"device"},{"action":"delete","action_detail":"delete_device","permission_id":98488,"permission_type_id":21,"target_type":"device"},{"action":"read","action_detail":"get_device","permission_id":98489,"permission_type_id":22,"target_type":"device"},{"action":"read device","action_detail":"get_device_keys","permission_id":98490,"permission_type_id":38,"target_type":"device"},{"action":"read","action_detail":"get_device_datasource_schemas","permission_id":98491,"permission_type_id":49,"qualifier":"schemas","target_type":"device"},{"action":"read device","action_detail":"get_device_datasources","permission_id":98492,"permission_type_id":62,"target_type":"device"}],"secret_token":"krlpnrztlwyzpkxosstuzlywuonxnums"}}}
GET /device/{device_id}/keys

Route parameters

device_id string

  • Device id to request keys for

Query string parameters

with_permissions boolean

  • Include or omit the permission space for the objects returned

Description

This API allows retrieval of the keys for a particular device. It is not possible to request keys for a device belonging to a customer other than the one that owns the API key being used in the request.

Response definition

keys array [key :: object]

  • The keys that are assigned to this device
  • See Get Key for response definition

device_id uuid

  • The unique identifier for this device

Examples

Request

GET /v1/device/3a4bf4be-5cc2-4a88-b2a6-fdf888b6a007/keys?with_permissions=true

Response

{"status":"ok","data":{"device_id":"3a4bf4be-5cc2-4a88-b2a6-fdf888b6a007","keys":[{"assigned_key_permission_sets":[],"assigned_key_permissions":[],"created":"2016-12-02 20:32:47.541652","cross_customer_enabled":false,"is_active":true,"is_admin":false,"is_deleted":false,"key_id":"xovruxnwxltqpnknyxmnxkvooslrmylt","object_id":"70140f8d-912a-4952-90d8-d380bc80578f","owner_customer_id":"13855d51-5922-4a00-a9fe-dd87204c8721","owner_id":"3a4bf4be-5cc2-4a88-b2a6-fdf888b6a007","owner_type":"D","permissions":[{"action":"deactivate","action_detail":"deactivate_key","permission_id":98493,"permission_type_id":26,"target_type":"api key"},{"action":"activate","action_detail":"activate_key","permission_id":98494,"permission_type_id":27,"target_type":"api key"},{"action":"delete","action_detail":"delete_key","permission_id":98495,"permission_type_id":28,"target_type":"api key"},{"action":"grant","action_detail":"grant_key_permissions","permission_id":98496,"permission_type_id":29,"qualifier":"permissions","target_type":"api key"},{"action":"revoke","action_detail":"revoke_key_permissions","permission_id":98497,"permission_type_id":30,"qualifier":"permissions","target_type":"api key"},{"action":"add","action_detail":"add_permission_sets_to_key","permission_id":98498,"permission_type_id":31,"qualifier":"permission sets","target_type":"api key"},{"action":"remove","action_detail":"remove_permission_sets_from_key","permission_id":98499,"permission_type_id":32,"qualifier":"permission sets","target_type":"api key"},{"action":"upgrade","action_detail":"enable_key_cross_customer","permission_id":98500,"permission_type_id":34,"target_type":"api key"},{"action":"downgrade","action_detail":"disable_key_cross_customer","permission_id":98501,"permission_type_id":35,"target_type":"api key"},{"action":"read","action_detail":"get_key","permission_id":98502,"permission_type_id":36,"target_type":"api key"},{"action":"read","action_detail":"get_key_shared_secret","permission_id":98503,"permission_type_id":103,"target_type":"api key"}]}]}}
PUT /device/{device_id}

Route parameters

device_id string

  • Device id to update

Body parameters

name string

  • The name to give the device
  • Must be globally unique

create_new_token boolean

  • Whether or not to create a new secret token for HMAC authentication
  • A device may have only one secret token at a time

Description

This provides a mechanism for certain parameters of a device to be modified, provided that the requester has object permissions to do so.

Name conflicts

Device names are unique within a given customer. Attempts to modify a device that would result in a conflict will return an error.

Response definition

device_id uuid

  • The unique identifier for this device

customer_id uuid

  • The unique identifier for the customer that owns this device

name string

  • The name of the device

is_active boolean

  • Whether or not this device is active and usable

secret_token string

  • The secret token for this device, used as part of API authentication

Examples

Request

PUT /device/ff61ac8b-1fda-4f43-928d-79790b7791fd

Body

{"data":{"name": "newname","create_new_token":true}}

Response

{"status":"ok", "data":{"device": {"device_id": "ff61ac8b-1fda-4f43-928d-79790b7791fd","customer_id":"28fbe0a9-bb7f-4935-8e86-4e75db35bd6f","secret_token":"xt47r0mMCWcR6PcAjwg9GrkbYCrAMmb","name": "newname","is_active": true}}}

Keys and Permissions

Overview

DB4IoT has a strong authorization system based on the concept of granular permissions. Keys are granted permissions, and authorized to perform actions.

Available APIs

PUT /key/{key_id}/activate

Route parameters

key_id string

  • Key id to mark activated

Description

This API allows for keys to be marked as activated. Newly created keys already active. The key can be deactivated at any time, which suspends the ability for that key to interact with the system.

Examples

Request

PUT /key/xvCEqCACIWotMJGkLeGGgYLomS6bf/activate

Response

{"status":"ok", "data":{}}
PUT /key/{key_id}/deactivate

Route parameters

key_id string

  • Key id to mark deactivated

Description

This API allows for keys to be marked as deactivated. The key may no longer make API requests or otherwise interact with the system. The key can be reactivated at any time.

Examples

Request

PUT /key/xvCEqCACIWotMJGkLeGGgYLomS6bf/deactivate

Response

{"status":"ok", "data":{}}
DELETE /key/{key_id}

Route parameters

key_id string

  • Key id to mark deleted

Description

This API allows for keys to be marked as deleted. The key can never be used again. Deleted keys are retained in the system for record-keeping purposes.

Examples

Request

DELETE /key/xvCEqCACIWotMJGkLeGGgYLomS6bf

Response

{"status":"ok", "data":{}}
GET /key/{key_id}

Route parameters

key_id string

  • Key id to retrieve

Query string parameters

with_permissions boolean

  • Include or omit the permission space for this object

Description

This command returns information about a key including the list of assigned permissions, provided that the requester has object permissions to view this information. If "with_permissions" is true, the space of object permissions that apply to the key will be returned as well.

Response definition

permissions array [permission :: object]

  • The set of object permissions that apply to this key
  • See Keys and Permissions for response definition

created timestamp

  • The ISO 8601 creation timestamp

is_active boolean

  • Whether or not this object is active and usable

is_deleted boolean

  • Whether or not this object is deleted and no longer valid

key_id string

  • The identifier for this key used in API authentication

object_id uuid

  • The unique identifier for this object

owner_customer_id uuid

  • The customer identifier for the user or device that owns this key

owner_id uuid

  • The unique identifier for the user or device that owns this key

owner_type string

  • One of 'D' (device) or 'U' (user)

Examples

Request

GET /v1/key/xovruxnwxltqpnknyxmnxkvooslrmylt?with_permissions=true

Response

{"status":"ok","data":{"key":{"assigned_key_permission_sets":[],"assigned_key_permissions":[],"created":"2016-12-02 20:32:47.541652","cross_customer_enabled":false,"is_active":true,"is_admin":false,"is_deleted":false,"key_id":"xovruxnwxltqpnknyxmnxkvooslrmylt","object_id":"70140f8d-912a-4952-90d8-d380bc80578f","owner_customer_id":"13855d51-5922-4a00-a9fe-dd87204c8721","owner_id":"3a4bf4be-5cc2-4a88-b2a6-fdf888b6a007","owner_type":"D","permissions":[{"action":"deactivate","action_detail":"deactivate_key","permission_id":98493,"permission_type_id":26,"target_type":"api key"},{"action":"activate","action_detail":"activate_key","permission_id":98494,"permission_type_id":27,"target_type":"api key"},{"action":"delete","action_detail":"delete_key","permission_id":98495,"permission_type_id":28,"target_type":"api key"},{"action":"grant","action_detail":"grant_key_permissions","permission_id":98496,"permission_type_id":29,"qualifier":"permissions","target_type":"api key"},{"action":"revoke","action_detail":"revoke_key_permissions","permission_id":98497,"permission_type_id":30,"qualifier":"permissions","target_type":"api key"},{"action":"add","action_detail":"add_permission_sets_to_key","permission_id":98498,"permission_type_id":31,"qualifier":"permission sets","target_type":"api key"},{"action":"remove","action_detail":"remove_permission_sets_from_key","permission_id":98499,"permission_type_id":32,"qualifier":"permission sets","target_type":"api key"},{"action":"upgrade","action_detail":"enable_key_cross_customer","permission_id":98500,"permission_type_id":34,"target_type":"api key"},{"action":"downgrade","action_detail":"disable_key_cross_customer","permission_id":98501,"permission_type_id":35,"target_type":"api key"},{"action":"read","action_detail":"get_key","permission_id":98502,"permission_type_id":36,"target_type":"api key"},{"action":"read","action_detail":"get_key_shared_secret","permission_id":98503,"permission_type_id":103,"target_type":"api key"}]}}}
PUT /key/{key_id}/permissions

Route parameters

key_id string

  • Key id to grant permissions to

Body parameters

permissions array [int]

  • The permissions to be granted

Response definition

key_id string

  • Key id operated on

assigned_key_permission_ids array [int]

  • The complete list of permission ids assigned to this key after the grant call is complete

permission_ids_granted array [int]

  • Permission ids that were granted to the key

permission_ids_not_found array [int]

  • Permission ids that were not found

Description

This API allows for keys to be granted one or more object or abstract permissions. The key being used to authenticate the request must have the appropriate permissions to manipulate the target key as well as the authority to grant the particular object or abstract permissions requested.

Examples

Request

PUT /key/xvCEqCACIWotMJGkLeGGgYLomS6bf/permissions

Body

{"data":{"permissions":[5782,5783,5784]}}

Response

{"status":"ok","data":{"assigned_key_permission_ids":[5782,5783,5784],"key_id":"xvCEqCACIWotMJGkLeGGgYLomS6bf","permission_ids_granted":[5782,5783,5784],"permission_ids_not_found":[]}}
DELETE /key/{key_id}/permissions

Route parameters

key_id string

  • Key id to revoke permissions from

Body parameters

permissions array [int]

  • The permissions to be revoked

Response definition

key_id string

  • Key id operated on

assigned_key_permission_ids array [int]

  • The complete list of permission ids assigned to this key after the revocation call is complete

permission_ids_revoked array [int]

  • Permission ids that were revoked from the key

permission_ids_not_found array [int]

  • Permission ids that were not found

Description

This API allows for the revocation of one or more object and abstract permissions from keys. The key being used to authenticate the request must have the appropriate permissions to manipulate the target key as well as the authority to revoke the particular object or abstract permissions requested.

Examples

Request

DELETE /key/xvCEqCACIWotMJGkLeGGgYLomS6bf/permissions

Body

{"data":{"permissions":[5782,5783,5784]}}

Response

{"status":"ok","data":{"assigned_key_permission_ids":[],"key_id":"xvCEqCACIWotMJGkLeGGgYLomS6bf","permission_ids_revoked":[5782,5783,5784],"permission_ids_not_found":[]}}

Keys

A key may be thought of as a container for zero or more unsigned integer permission ids. Keys are the primary method of authorizing access to DB4IoT APIs, and by default do not contain permissions to perform any action when they are first created.

Permissions

A permission is an atomic unit of authorization. They uniquely identify a verb (such as create, modify, read) with a noun (an object id). Permissions are granted and revoked as desired to and from keys, and their presence determines what a key may do within a customer space. There are three different permission classes: abstract, object, and generic.

Abstract, object, and generic permission classes

Abstract permissions

Abstract permissions pertain to actions that create objects. For example, the creation of users, devices, and datasources are all governed by abstract permissions. These permissions are relatively powerful, allowing for the creation of objects within your customer space. They should be granted with care.

Object permissions

Every object (user, device, datasource, even keys themselves) have a set of permissions that apply to that specific object. These permissions are generated at creation time, and are not granted by default to any key. When an object permission is granted to a key, that key gains the ability to perform a specific action on the single object that owns the permission being granted.

Object permissions are the most granular level of access control offered by the DB4IoT API. Using them as the primary means of opening up access to objects in your customer space provides maximum control, at the cost of additional setup and planning.

Generic permissions

While object permissions pertain only to single objects, generic permissions apply to all objects of a given type. For example, one might grant a generic permission to get_user to a key, which enables that key to run GET /user/{user_id} API requests against any user_id in that key's customer space. Generic permissions are a very powerful means of granting particular actions across the entire set of objects of a particular type in your customer space. Because they operate at the type level, and not the object level, these permissions should be granted with extreme care (particularly those permissions that deal with deleting objects).

Generic permissions are the most convenient way of adding capabilities to keys, but come at the cost of granularity and exposing the need to be very cautious about the types of actions and types that are granted to keys.

Permission space and the with_permissions parameter

When an object is created (such as a user, device, or datasource), the API response will contain a "permission space" of permissions that apply to that specific created object. These new permission ids may then be added to keys, granting access to specific actions.

Furthermore, all APIs that allow for the retrieval of previously created objects may have requests with the optional with_permissions parameter provided. When provided, the response will contain the permission space for the object(s). This is the same information that is provided in the original creation response, as described above.

Permission Response Definition

For many administrative APIs, calls can be made "with_permissions" in order to return object permissions for entities such as users, devices, etc. Additionally, when using some Key APIs (such as "Get Key") the "assigned_key_permissions" array in the response will contain "permission" objects. The following defines what a "permission" object consists of:

action string

  • A broad category for the type of ability this permission grants

action_detail string

  • A specific descriptor for the type of ability this permission grants

permission_id int

  • A serial key that uniquely identifies a particular permission

permission_type_id int

  • An internal identifier for classifying permission types

target_type string

  • The entity type that the permission applies to, such as 'device', 'user', 'customer'

target_object_id uuid

  • The object that the permission applies to - omitted when appearing in the context of a response where the target id is already known

Password

Overview

The Password API provides programmatic access to user passwords, which are in turn used to obtain API access. They are, essentially, a means of exchanging something memorable (a password) for a user secret_token and zero or more keys assigned to that user.

You are encouraged to cache secret_token and keys obtained via the Get Password Credentials API. It is not necessary to use the Password API as a means of authentication - API access is already checked at the key level.

Available APIs

GET /credentials

Query string parameters

customer_name string

  • The name of the customer that owns the user provided in 'user_name'

user_name string

  • The name of the user that owns the credentials being retrieved

password string

  • The password to be used for retrieval of user credentials

with_permissions boolean

  • Include or omit the permission space for this object
  • Default value: false

with_detail boolean

  • Include or omit information about the assigned permissions on the returned keys
  • Default value: true

Description

This endpoint is used for retreiving user API credentials using a password.

Response definition

customer_id uuid

  • The unique identifier for the customer that owns this user

user_id uuid

  • The unique identifier for this user

secret_token string

  • The secret token associated with this user

expires ISO-8601 date

  • The date and time at which the password for this user expires

keys array [key :: object]

  • An array of keys assigned to the user

Examples

Request

GET /credentials?customer_name=&My+Customer&user_name=My+User&with_permissions=true

Response

{"status":"ok","data":{"password_info":{"customer_id":"c819eba0-06a8-475c-8b6e-d58f5f58aae5","user_id":"a893eaad-4abb-47cf-855b-35920da34971","secret_token":"xpokkrpxuyvtqttnzpsxnqsyptvpsxzk","expires":"2017-02-28 17:35:17.39683","keys":[{"key_id":"rnrlnstkkxrknvkpplnpvolsuzpontxm","object_id":"09eceabe-50a6-4a8b-a1b0-dd65daf52b7e","owner_type":"U","owner_id":"a893eaad-4abb-47cf-855b-35920da34971","owner_customer_id":"c819eba0-06a8-475c-8b6e-d58f5f58aae5","is_active":true,"is_deleted":false,"is_admin":true,"cross_customer_enabled":true,"created":"2016-04-15 20:24:28.932411","assigned_key_permissions":[{"permission_id":1,"permission_type_id":1,"action":"create","target_type":"customer","action_detail":"create_customer","target_object_id":"any customer","target_is_generic":false},{"permission_id":2,"permission_type_id":7,"action":"read all","target_type":"customer","action_detail":"get_all_customers","target_object_id":"any customer","target_is_generic":false},{"permission_id":128,"permission_type_id":113,"action":"modify","target_type":"data node","action_detail":"delete_data_node_mapping","target_object_id":"4a455427-73d6-4593-bd09-bfe5f106b6e9","target_is_generic":true}],"assigned_key_permission_sets":[],"permissions":[{"permission_id":144,"permission_type_id":26,"action":"deactivate","target_type":"api key","action_detail":"deactivate_key"},{"permission_id":154,"permission_type_id":103,"action":"read","target_type":"api key","action_detail":"get_key_shared_secret"}]}]}}}
POST /password/replace

Body parameters

customer_name string

  • The name of the customer that owns the user being targeted

user_name string

  • The name of the user to replace a password for

reset_token string

  • The valid reset token that was emailed to the primary contact email for the user

password string

  • A valid candidate password to replace the users current password with

Description

This endpoint is used for completing the password reset process, which results in a new valid password being set for the user. A valid reset token must be supplied - only the most recently generated reset token is considered valid.

Response definition

customer_id uuid

  • The unique identifier for the customer that owns this user

user_id uuid

  • The unique identifier for this user

password_expires ISO-8601 date

  • The date and time when the new password expires

Examples

Request

POST /password/reset

Body

{"data":{"customer_name":"My Customer","user_name":"My User","reset_token":"DhHDFaEACAedfHCgHaaAfbfBabBdhGcb","password":"Ai51jJ!op"}}

Response

{"result": {"status": "ok","password_info": {"customer_id": "c819eba0-06a8-475c-8b6e-d58f5f58aae5","user_id": "a893eaad-4abb-47cf-855b-35920da34971","password_expires": "2017-11-20 18:06:19.842157"}}}
POST /password/reset

Body parameters

customer_name string

  • The name of the customer that owns the user being targeted

user_name string

  • The name of the user to receive a reset notification

Description

This endpoint is used for initiating password reset notifications. These notifications and instructions on how to complete the reset process are sent to the primary contact email for the user being targeted.

Response definition

customer_id uuid

  • The unique identifier for the customer that owns this user

user_id uuid

  • The unique identifier for this user

reset_token string

  • The reset token to be used when submitting a new password through the replace API

reset_token_expires ISO-8601 date

  • The date and time at which the reset token for this user expires

Examples

Request

POST /password/reset

Body

{"data":{"customer_name":"My Customer","user_name":"My User"}}

Response

{"result": {"status": "ok","password_info": {"customer_id": "c819eba0-06a8-475c-8b6e-d58f5f58aae5","user_id": "a893eaad-4abb-47cf-855b-35920da34971","reset_token": "DhHDFaEACAedfHCgHaaAfbfBabBdhGcb","reset_token_expires": "2016-11-26 18:02:12.904132"}}}

Strength requirements

Passwords have a number of restrictions:

  • Must be at least eight characters in length.
  • Must contain at least one of each of the following: upper case alphabetical, lower case alphabetical, numeric, and punctuation.
  • The backslash "\" character is not permitted.
  • Predictable alphanumeric sequences are not allowed.

Expiration policy

All passwords expire after 1 year. Once a password expires, it is no longer valid for use with the Get Password Credentials API. Once expired, you must use the Reset Password API and follow the emailed instructions to submit a new password.

Reuse policy

All password submissions are kept for a historical record, and used to check against newly submitted passwords. Any password submitted within the last 6 months may not be reused.

Failed attempt lockout

After 5 unsuccessful accesses of the Get Password Credentials API, a password is "locked". Locked passwords are effectively expired, and must be reset with a new password.

Creating a password for the first time

When a user is first created, it does not have a password. To begin the password creation process, make a call to the Get Password Credentials API with a non-empty password. You may use any non-empty string value, such as "new". In the returned error, an error code of 721 accompanied by the message New password record; reset required indicates that indeed, a new placeholder password record was created. Next, call the Reset Password API. This is will send an email to the contact_email for the user being targeted for the reset. Following the link in the email will take the user to a page where they may enter their new password.

Resetting a forgotten/expired/locked password

Call the Reset Password API, and follow the emailed instructions.

User

Overview

Users are objects that represent human actors within a customer. A user contains metadata such as an email, as well as a unique password that may be used to obtain API keys and the unique secret_token for that user.

Much like devices, users are fundamentally containers for zero or more keys. The difference is that users support the fetching of API credentials by password, as well as a reset/change password workflow that devices do not support.

Available APIs

PUT /user/{user_id}/activate

Route parameters

user_id string

  • User id to mark activated

Description

This API allows for users to be marked as activated. Newly created users already active. The user can be deactivated at any time, which suspends the ability for that user to interact with the system.

Examples

Request

PUT /user/16628a92-5693-49f3-ad92-56261f20f46d/activate

Response

{"status":"ok", "data":{}}
POST /user/{user_id}/datasource_schemas

Route parameters

user_id string

  • User id to use as the owner for this datasource schema

Body parameters

name string

  • The name to give the datasource_schema
  • Must be unique within the customer

engine_type string

  • The processing engine this schema is for, currently only "ephemeris"

schema_data object

  • The valid JSON schema definition for the selected engine_type

Description

This endpoint is used for creating datasource schemas with user owners. Note that devices may also create datasource schemas through Create Datasource Schema (Device owner).

Response definition

customer_id uuid

  • The unique identifier for the customer that owns this datasource schema

owner_id uuid

  • The unique identifier for the user that owns this datasource_schema

owner_type string

  • Always 'U' (user)

owner_type_id int

  • The identifier for the owner_type of this datasource schema

datasource_schema_id uuid

  • The unique identifier for this datasource_schema

name string

  • The name of the datasource_schema

schema_data object

  • A JSON object that defines the datasource schema as it will be applied to the given engine_type

engine_type string

  • The name of the engine that this datasource schema applies to

engine_type_id int

  • The identifier for the engine_type of this datasource schema

permissions array [permission :: object]

  • The set of object permissions that apply to this datasource_schema
  • See Keys and Permissions for response definition

Examples

Request

POST /user/8d5fc165-e86c-4fc5-8121-5d967e04317d/datasource_schemas

Body

{"data":{"name": "Datasource Schema 2", "customer_id": "28fbe0a9-bb7f-4935-8e86-4e75db35bd6f","schema_data":{"key":[{"type":"uuid","column_id":"id"}],"static_columns":[{"type":"selector","column_id":"model","attributes":{"values":["Phantom","Matrice100","AirborneNight","AirborneCargo","Hydrofoil","JumpingNight","JumpingRace","MatternetONE","EVOLUTION3"]}},{"type":"selector","column_id":"make","attributes":{"values":["DajiangInnovation","ParrotEPA","Matternet","Skycatch"]}}],"time_series_columns":[{"type":"integer","column_id":"fuel","attributes":{"min_value":0,"max_value":100000}},{"type":"selector","column_id":"charging","attributes":{"values":["Charging","Discharging"]}},{"type":"geographic_point","column_id":"point","attributes":{"latitude":"lat","longitude":"long"}}]}}}

Response

{"status":"ok","data":{"datasource_schema":{"customer_id":"fcd63a01-953d-4fb7-8de0-1ade381ed010","engine_type_id":"2","datasource_schema_id":"51258f04-e29e-4e93-88c1-16de324e259d","name":"Datasource Schema 2","owner_id":"8d5fc165-e86c-4fc5-8121-5d967e04317d","owner_type":"U","owner_type_id":"4","permissions":[{"action":"modify","action_detail":"modify_datasource_schema","permission_id":31035,"permission_type_id":37,"target_type":"datasource schema"},{"action":"delete","action_detail":"delete_datasource_schema","permission_id":31036,"permission_type_id":38,"target_type":"datasource schema"},{"action":"read","action_detail":"get_datasource_schema","permission_id":31037,"permission_type_id":39,"target_type":"datasource schema"}],"schema_data":{"key":[{"type":"uuid","column_id":"id"}],"static_columns":[{"type":"selector","column_id":"model","attributes":{"values":["Phantom","Matrice100","AirborneNight","AirborneCargo","Hydrofoil","JumpingNight","JumpingRace","MatternetONE","EVOLUTION3"]}},{"type":"selector","column_id":"make","attributes":{"values":["DajiangInnovation","ParrotEPA","Matternet","Skycatch"]}}],"time_series_columns":[{"type":"integer","column_id":"fuel","attributes":{"min_value":0,"max_value":100000}},{"type":"selector","column_id":"charging","attributes":{"values":["Charging","Discharging"]}},{"type":"geographic_point","column_id":"point","attributes":{"latitude":"lat","longitude":"long"}}]}}}}
POST /user/{user_id}/keys

Route parameters

user_id string

Description

This endpoint is used for creating a key and attaching it to a user.

Response definition

key_id string

  • The identifier for this key used in API authentication

object_id uuid

  • The unique identifier for this object

owner_id uuid

  • The unique identifier for the user or device that owns this key

owner_type string

  • For this call, always 'U' (user)

permissions array [permission :: object]

  • The set of object permissions that apply to this key

Examples

Request

POST /user/0f267db6-0f9a-4a07-98cd-addf5e834f6a/keys

Body

{"data":{"name":"New User Key"}}

Response

{"status":"ok","data":{"key":{"customer_id":"13855d51-5922-4a00-a9fe-dd87204c8721","key_id":"omlxtwunyymmqonlnrrouyzvpyxstsvl","object_id":"08567364-4d5c-48c4-92a2-77a3b0bf782d","owner_id":"0f267db6-0f9a-4a07-98cd-addf5e834f6a","owner_type":"U","owner_type_id":8,"permissions":[{"action":"deactivate","action_detail":"deactivate_key","permission_id":98504,"permission_type_id":26,"target_type":"api key"},{"action":"activate","action_detail":"activate_key","permission_id":98505,"permission_type_id":27,"target_type":"api key"},{"action":"delete","action_detail":"delete_key","permission_id":98506,"permission_type_id":28,"target_type":"api key"},{"action":"grant","action_detail":"grant_key_permissions","permission_id":98507,"permission_type_id":29,"qualifier":"permissions","target_type":"api key"},{"action":"revoke","action_detail":"revoke_key_permissions","permission_id":98508,"permission_type_id":30,"qualifier":"permissions","target_type":"api key"},{"action":"add","action_detail":"add_permission_sets_to_key","permission_id":98509,"permission_type_id":31,"qualifier":"permission sets","target_type":"api key"},{"action":"remove","action_detail":"remove_permission_sets_from_key","permission_id":98510,"permission_type_id":32,"qualifier":"permission sets","target_type":"api key"},{"action":"upgrade","action_detail":"enable_key_cross_customer","permission_id":98511,"permission_type_id":34,"target_type":"api key"},{"action":"downgrade","action_detail":"disable_key_cross_customer","permission_id":98512,"permission_type_id":35,"target_type":"api key"},{"action":"read","action_detail":"get_key","permission_id":98513,"permission_type_id":36,"target_type":"api key"},{"action":"read","action_detail":"get_key_shared_secret","permission_id":98514,"permission_type_id":103,"target_type":"api key"}]}}}
PUT /user/{user_id}/deactivate

Route parameters

user_id string

  • User id to mark deactivated

Description

This API allows for users to be marked as deactivated. The user may no longer make API requests or otherwise interact with the system. The user can be reactivated at any time.

Examples

Request

PUT /user/16628a92-5693-49f3-ad92-56261f20f46d/deactivate

Response

{"status":"ok", "data":{}}
DELETE /user/{user_id}

Route parameters

user_id string

  • User id to mark deleted

Description

This API allows for users to be marked as deleted. The user can no longer be modified, and any keys it has been assigned will cease to function. Deleted users are retained in the system for record-keeping purposes.

Examples

Request

DELETE /user/16628a92-5693-49f3-ad92-56261f20f46d

Response

{"status":"ok", "data":{}}
GET /user/{user_id}

Route parameters

user_id string

  • User id to retrieve

Query string parameters

with_permissions boolean

  • Include or omit the permission space for this object

Description

This command returns information about a user, provided that the requester has object permissions to view this information. If "with_permissions" is true, the space of object permissions that apply to the user will be returned as well.

Response definition

user_id uuid

  • The unique identifier for this user

email email

  • The email address for this user

name string

  • The name of the user

customer_id uuid

  • The unique identifier for the customer that owns this user

created timestamp

  • An ISO 8601 timestamp for when the user was created

is_active boolean

  • Whether or not this user is active and usable

is_deleted boolean

  • Whether or not this user is deleted and no longer valid

permissions array [permission :: object]

  • The set of object permissions that apply to this user
  • See Keys and Permissions for response definition

Examples

Request

GET /user/0f267db6-0f9a-4a07-98cd-addf5e834f6a?with_permissions=true

Response

{"status":"ok","data":{"user":{"created":"2016-12-02 20:20:07.223423","customer_id":"13855d51-5922-4a00-a9fe-dd87204c8721","email":"new.user@hello.com","is_active":true,"is_deleted":false,"is_superuser":false,"name":"new.user","permissions":[{"action":"modify","action_detail":"modify_user","permission_id":98477,"permission_type_id":11,"target_type":"user"},{"action":"deactivate","action_detail":"deactivate_user","permission_id":98478,"permission_type_id":12,"target_type":"user"},{"action":"activate","action_detail":"activate_user","permission_id":98479,"permission_type_id":13,"target_type":"user"},{"action":"delete","action_detail":"delete_user","permission_id":98480,"permission_type_id":14,"target_type":"user"},{"action":"read","action_detail":"get_user","permission_id":98481,"permission_type_id":15,"target_type":"user"},{"action":"read user","action_detail":"get_user_keys","permission_id":98482,"permission_type_id":39,"target_type":"user"},{"action":"read","action_detail":"get_user_datasource_schemas","permission_id":98483,"permission_type_id":48,"qualifier":"schemas","target_type":"user"},{"action":"read user","action_detail":"get_user_datasources","permission_id":98484,"permission_type_id":63,"target_type":"user"}],"secret_token":"stvpomurznstkwotywzvsvsnvlozvxoo","user_id":"0f267db6-0f9a-4a07-98cd-addf5e834f6a"}}}
GET /user/{user_id}/keys

Route parameters

user_id string

  • User id to request keys for

Query string parameters

with_permissions boolean

  • Include or omit the permission space for the objects returned

Description

This API allows retrieval of the keys for a particular user. It is not possible to request keys for a user belonging to a customer other than the one that owns the API key being used in the request.

Response definition

keys array [key :: object]

  • The keys that are assigned to this user
  • See Get Key for response definition

user_id uuid

  • The unique identifier for this user

Examples

Request

GET /user/0f267db6-0f9a-4a07-98cd-addf5e834f6a/keys?with_permissions=true

Response

{"status":"ok","data":{"keys":[{"assigned_key_permission_sets":[],"assigned_key_permissions":[],"created":"2016-12-02 20:37:51.871541","cross_customer_enabled":false,"is_active":true,"is_admin":false,"is_deleted":false,"key_id":"omlxtwunyymmqonlnrrouyzvpyxstsvl","object_id":"08567364-4d5c-48c4-92a2-77a3b0bf782d","owner_customer_id":"13855d51-5922-4a00-a9fe-dd87204c8721","owner_id":"0f267db6-0f9a-4a07-98cd-addf5e834f6a","owner_type":"U","permissions":[{"action":"deactivate","action_detail":"deactivate_key","permission_id":98504,"permission_type_id":26,"target_type":"api key"},{"action":"activate","action_detail":"activate_key","permission_id":98505,"permission_type_id":27,"target_type":"api key"},{"action":"delete","action_detail":"delete_key","permission_id":98506,"permission_type_id":28,"target_type":"api key"},{"action":"grant","action_detail":"grant_key_permissions","permission_id":98507,"permission_type_id":29,"qualifier":"permissions","target_type":"api key"},{"action":"revoke","action_detail":"revoke_key_permissions","permission_id":98508,"permission_type_id":30,"qualifier":"permissions","target_type":"api key"},{"action":"add","action_detail":"add_permission_sets_to_key","permission_id":98509,"permission_type_id":31,"qualifier":"permission sets","target_type":"api key"},{"action":"remove","action_detail":"remove_permission_sets_from_key","permission_id":98510,"permission_type_id":32,"qualifier":"permission sets","target_type":"api key"},{"action":"upgrade","action_detail":"enable_key_cross_customer","permission_id":98511,"permission_type_id":34,"target_type":"api key"},{"action":"downgrade","action_detail":"disable_key_cross_customer","permission_id":98512,"permission_type_id":35,"target_type":"api key"},{"action":"read","action_detail":"get_key","permission_id":98513,"permission_type_id":36,"target_type":"api key"},{"action":"read","action_detail":"get_key_shared_secret","permission_id":98514,"permission_type_id":103,"target_type":"api key"}]}],"user_id":"0f267db6-0f9a-4a07-98cd-addf5e834f6a"}}
PUT /user/{user_id}

Route parameters

user_id string

  • User id to update

Body parameters

name string

  • The name to give the user
  • Must be globally unique

email string

  • The primary contact email for the user

create_new_token boolean

  • Whether or not to create a new secret token for HMAC authentication
  • A user may have only one secret token at a time

Description

This provides a mechanism for certain parameters of a user to be modified, provided that the requester has object permissions to do so.

Name conflicts

User names are unique across the system. Attempts to modify a user that would result in a conflict will return an error.

Response definition

user_id uuid

  • The unique identifier for this user

customer_id uuid

  • The unique identifier for the customer that owns this user

name string

  • The name of the user

email email

  • The email address for this user

is_active boolean

  • Whether or not this user is active and usable

secret_token string

  • The secret token for this user, used as part of API authentication

Examples

Request

PUT /user/16628a92-5693-49f3-ad92-56261f20f46d

Body

{"data":{"name": "newname", "email": "test@hello.com", "create_new_token":true}}

Response

{"status":"ok", "data":{"user": {"user_id": "16628a92-5693-49f3-ad92-56261f20f46d","customer_id":"28fbe0a9-bb7f-4935-8e86-4e75db35bd6f","name": "newname","email": "test@hello.com","secret_token":"ymOLjKuPmb0S1W6cgPjP7Qbkx9I8Tlrb","is_active": true}}}

Data API

Overview

This collection of APIs provides push and analytics access for datasources. As with all APIs, requests to these endpoints must pass HMAC authentication and include all required headers.


The event_timestamp key

This is a special, reserved column of type timestamp with a column_id of "event_timestamp". It has attributes values for time_units_per_second of 1, and epoch that corresponds to the first event that exists in the datasource. This is in effect an index into a sequence of time series data. By default, the epoch is the UNIX epoch, which means that a timestamp value of 1 would correspond to Thu, 01 Jan 1970 00:00:01 GMT.

Thus, all event_timestamp values after the first value are offsets from the first value.

Note that event_timestamp is a reserved column_id and may not be used for any other column_id.

Analysis

Available APIs

GET /datasource/{datasource_id}/tile

Route parameters

datasource_id string

  • The id of the datasource to generate an image tile from.

Query string parameters

x integer

  • The 'X' coordinate of a mercator projection to use as part of the top left point used to bound the resulting tile.

y integer

  • The 'Y' coordinate of a mercator projection to use as part of the top left point used to bound the resulting tile.

zoom integer

  • The zoom level that defines how to interpret the provided x and y parameters within a mercator projection.

event_timestamp integer

  • The timestamp of the event that should be used for display.
  • Note that either 'event_timestamp' or BOTH 'event_timestamp_begin' and 'event_timestamp_end' must be provided, despite this parameter being listed as optional.

event_timestamp_begin integer

  • The starting inclusive timestamp of the event time range that should be used for display.
  • Note that either 'event_timestamp' or BOTH 'event_timestamp_begin' and 'event_timestamp_end' must be provided, despite this parameter being listed as optional.

event_timestamp_end integer

  • The ending exclusive timestamp of the event time range that should be used for display.
  • Note that either 'event_timestamp' or BOTH 'event_timestamp_begin' and 'event_timestamp_end' must be provided, despite this parameter being listed as optional.

dot_size integer

  • The size of the dots to be displayed in the image. This value must be a power of 2.
  • Default value: 32

dot_shape url-encoded JSON

  • Defines parameters for alternative methods of rendering markers, which are otherwise rendered as solid-color dots.

color_by string

  • The 'column_id' of the column to color data by.

color_mode string

  • Which method to color the data by, currently must be 'linear_interpolation'.
  • Default value: linear_interpolation

unknown_value_color hexadecimal color

  • The color to use for event_timestamp values that contain an 'unknown' value for the requested 'color_by' column.

undefined_value_color hexadecimal color

  • The color to use for event_timestamp values that contain an 'undefined' value for the requested 'color_by' column.

interpolated_colors hexadecimal color

  • An array of colors to perform interpolation with.
  • Multiple values for this parameter are interpreted in the order they are specified as an array.
  • Only used when 'color_mode' is 'linear_interpolation'.
  • Each provided interpolation step must be equidistant relative to the color wheel.

interpolated_value_colors url-encoded JSON

  • An array of value-color pairs to perform interpolation with.
  • Multiple values for this parameter are interpreted in the order they are specified as an array.
  • Only used when 'color_mode' is 'linear_interpolation'.
  • Each provided interpolation step must be equidistant relative to the color wheel.

filter url-encoded JSON

  • The filter that should be applied to the result set used to populate the image.
  • See the documentation on Filter for more details on how to structure this parameter prior to URL-encoding.

width integer

  • The desired width of the resulting image.
  • Must be a power of 2.
  • Default value: 256

coordinate_column string

  • The geographic_point column that should be used as the reference point for the tile.
  • Default value: If unspecified and the schema contains only a single geographic_point column, that column will be used as the default.

Description

This API returns a PNG image representing the underlying data. Tiles may be requested for any event_timestamp or event_timestamp range (using event_timestamp_begin and event_timestamp_end) and filter with a variety of display options.

Response definition

Image Tile png

Examples

Request

GET /datasource/b43766b2-76d5-4a88-a9d6-0e8cd754da56/tile?x=7&y=12&zoom=5&color_by=fuel&interpolated_colors=0x85144b&interpolated_colors=0xFF851B&interpolated_colors=0xFFDC00&dot_size=4&event_timestamp=5&width=256

Response

POST /datasource/{datasource_id}/analyze

Route parameters

datasource_id string

  • The id of the datasource to export data from

Body parameters

event_timestamp integer

  • The timestamp of the event to view in the result set.

event_timestamp_begin integer

  • The starting inclusive timestamp of the event time range that should be used for display.
  • Note that either 'event_timestamp' or BOTH 'event_timestamp_begin' and 'event_timestamp_end' must be provided, despite this parameter being listed as optional.

event_timestamp_end integer

  • The ending exclusive timestamp of the event time range that should be used for display.
  • Note that either 'event_timestamp' or BOTH 'event_timestamp_begin' and 'event_timestamp_end' must be provided, despite this parameter being listed as optional.

filter array [filter :: object]

  • The filter that should be applied to the result set.

columns array [column :: object]

  • The columns that should be included in the response.

offset integer

  • A left-hand offset into the result set.
  • Ex. For a result set of length 10, an offset of 5 would return result indices 5 through 10.

limit integer

  • The maximum number of results returned.
  • Ex. For a result set of length 10, a limit of 5 would return result indices 0 through 5.

compression_level integer

  • The degree of compression to use, from 1-9.
  • Higher values result in more compressed data, at the cost of being more expensive to compress.
  • Default value: 3

time_bin_size integer

  • Allows for the creation of a bucketed export at intervals over an event_timestamp_begin/end range.
  • This is commonly used to create aggregated exports over large time ranges. It serves to drastically reduce the size of exports as well as perform weighted averages over the interval.
  • The averaged column values are time-weighted, rounded up to the nearest value, and have the same type as the column itself.
  • If specified, any time series columns requested in the export must be numeric (integer or fixed_point). Keys and static columns may be of any type and are not averaged.

Description

This API produces a compressed or uncompressed CSV containing previously recorded event data. Exports may be requested for any event_timestamp or event_timestamp range (using event_timestamp_begin and event_timestamp_end), and filter with several optional parameters.

Response definition

Compressed or uncompressed csv

Examples

Request

POST /datasource/b43766b2-76d5-4a88-a9d6-0e8cd754da56/analyze

Body

{"data":{"method":"export_csv","event_timestamp":5,"columns":[{"column_id": "charging"},{"column_id": "make"},{"column_id": "model"},{"column_id": "fuel"}],"filter":{"logical":"and","conditions":[{"test":"match","column_id":"model","values":["Phantom","Matrice 100"]},{"test":"range","column_id":"fuel","from":0,"to":100000},{"test":"match","column_id":"charging","values":["Charging"]}]}}}

Response

"charging","make","model","fuel" "Charging","Dajiang Innovation","Phantom","1796" "Charging","Dajiang Innovation","Phantom","2355" "Charging","Dajiang Innovation","Phantom","2564" "Charging","Dajiang Innovation","Matrice 100","2951" "Charging","Dajiang Innovation","Matrice 100","2322" "Charging","Dajiang Innovation","Phantom","1569" "Charging","Dajiang Innovation","Matrice 100","2043" "Charging","Dajiang Innovation","Matrice 100","1903" "Charging","Dajiang Innovation","Matrice 100","2300" "Charging","Dajiang Innovation","Phantom","1333" "Charging","Dajiang Innovation","Matrice 100","2731" "Charging","Dajiang Innovation","Matrice 100","1198" "Charging","Dajiang Innovation","Matrice 100","2604" "Charging","Dajiang Innovation","Matrice 100","1590" "Charging","Dajiang Innovation","Matrice 100","1112" "Charging","Dajiang Innovation","Matrice 100","1234" "Charging","Dajiang Innovation","Matrice 100","2004" "Charging","Dajiang Innovation","Matrice 100","1427" "Charging","Dajiang Innovation","Matrice 100","2956" "Charging","Dajiang Innovation","Phantom","2209" "Charging","Dajiang Innovation","Phantom","1234" "Charging","Dajiang Innovation","Phantom","2767" "Charging","Dajiang Innovation","Matrice 100","1618" "Charging","Dajiang Innovation","Phantom","1368" "Charging","Dajiang Innovation","Phantom","2991" "Charging","Dajiang Innovation","Matrice 100","1423" "Charging","Dajiang Innovation","Matrice 100","1525" "Charging","Dajiang Innovation","Phantom","1103" "Charging","Dajiang Innovation","Matrice 100","2811" "Charging","Dajiang Innovation","Matrice 100","2945" "Charging","Dajiang Innovation","Matrice 100","2780" "Charging","Dajiang Innovation","Matrice 100","1054" "Charging","Dajiang Innovation","Matrice 100","1983" "Charging","Dajiang Innovation","Phantom","2167" "Charging","Dajiang Innovation","Phantom","1770" "Charging","Dajiang Innovation","Matrice 100","1326" "Charging","Dajiang Innovation","Matrice 100","1786" "Charging","Dajiang Innovation","Matrice 100","2846" "Charging","Dajiang Innovation","Matrice 100","2595" "Charging","Dajiang Innovation","Matrice 100","2346" "Charging","Dajiang Innovation","Matrice 100","1995" "Charging","Dajiang Innovation","Phantom","2179" "Charging","Dajiang Innovation","Phantom","2978" "Charging","Dajiang Innovation","Matrice 100","1567" "Charging","Dajiang Innovation","Matrice 100","2897" "Charging","Dajiang Innovation","Phantom","1484" "Charging","Dajiang Innovation","Phantom","1644" "Charging","Dajiang Innovation","Matrice 100","1466" "Charging","Dajiang Innovation","Matrice 100","1128" "Charging","Dajiang Innovation","Phantom","1043" "Charging","Dajiang Innovation","Phantom","1044"
POST /datasource/{datasource_id}/analyze

Route parameters

datasource_id string

  • The id of the datasource to export data from

Body parameters

event_timestamp integer

  • The timestamp of the event to view in the result set.

event_timestamp_begin integer

  • The starting inclusive timestamp of the event time range that should be used for display.
  • Note that either 'event_timestamp' or BOTH 'event_timestamp_begin' and 'event_timestamp_end' must be provided, despite this parameter being listed as optional.

event_timestamp_end integer

  • The ending exclusive timestamp of the event time range that should be used for display.
  • Note that either 'event_timestamp' or BOTH 'event_timestamp_begin' and 'event_timestamp_end' must be provided, despite this parameter being listed as optional.

filter array [filter :: object]

  • The filter that should be applied to the result set.

columns array [column :: object]

  • The columns that should be included in the response.

offset integer

  • A left-hand offset into the result set.
  • Ex. For a result set of length 10, an offset of 5 would return result indices 5 through 10.

limit integer

  • The maximum number of results returned.
  • Ex. For a result set of length 10, a limit of 5 would return result indices 0 through 5.

geo_json_point integer

  • A column_id for a geographic_point type to create Geographic JSON for.

time_bin_size integer

  • Allows for the creation of a bucketed export at intervals over an event_timestamp_begin/end range.
  • This is commonly used to create aggregated exports over large time ranges. It serves to drastically reduce the size of exports as well as perform weighted averages over the interval.
  • The averaged column values are time-weighted, rounded up to the nearest value, and have the same type as the column itself.
  • If specified, any time series columns requested in the export must be numeric (integer or fixed_point). Keys and static columns may be of any type and are not averaged.

Description

This API produces a JSON body containing previously recorded event data. Exports may be requested for any event_timestamp or event_timestamp range (using event_timestamp_begin and event_timestamp_end), and filter with several optional parameters. Optionally, a column of type geographic_point may be provided to the 'geo_json_point' option, which will output proper Geographic JSON for the provided column.

Response definition

json

Examples

Request

POST /datasource/de305d54-75b4-431b-adb2-eb6b9e546014/analyze

Body

{"method":"export_json","geo_json_point":"point","columns":[{"column_id":"id1"},{"column_id":"s1"},{"column_id":"t1"},{"column_id":"s2"},{"column_id":"t2"},{"column_id":"point"},{"column_id":"dir"}],"event_timestamp":100000}

Response

{"status":"ok","data":{"datasource_id":"_test_stream","data":{"type":"FeatureCollection","features":[{"type":"Feature","geometry":{"type":"Point","coordinates":[-123.08667,44.051944]},"properties":{"id1":"Eugene","s1":100000,"t1":100000,"s2":"Eugene","t2":"Eugene","lat":44.051944,"long":-123.08667,"dir":"west"}},{"type":"Feature","geometry":{"type":"Point","coordinates":[-123.28333,44.566667]},"properties":{"id1":"Corvallis","s1":300000,"t1":300000,"s2":"Corvallis","t2":"Corvallis","lat":44.566667,"long":-123.28333,"dir":"west"}},{"type":"Feature","geometry":{"type":"Point","coordinates":[-123.02889,44.930833]},"properties":{"id1":"Salem","s1":400000,"t1":400000,"s2":"Salem","t2":"Salem","lat":44.930833,"long":-123.02889,"dir":"west"}},{"type":"Feature","geometry":{"type":"Point","coordinates":[-121.3,44.05]},"properties":{"id1":"Bend","s1":0,"t1":0,"s2":"Bend","t2":"Bend","lat":44.05,"long":-121.3,"dir":"east"}}]},"time_in_usec":1611}}

Request

POST /datasource/b43766b2-76d5-4a88-a9d6-0e8cd754da56/analyze

Body

{"data":{"method":"export_json","event_timestamp":5,"columns":[{"column_id": "charging"},{"column_id": "make"},{"column_id": "model"},{"column_id": "fuel"}],"filter":{"logical":"and","conditions":[{"test":"match","column_id":"model","values":["Phantom","Matrice 100"]},{"test":"range","column_id":"fuel","from":0,"to":100000},{"test":"match","column_id":"charging","values":["Charging"]}]}}}

Response

POST /datasource/{datasource_id}/analyze

Route parameters

datasource_id string

  • The id of the datasource to obtain minimum and maximum event time ranges from

Description

This API returns the highest and lowest values in the range of event timestamps for the provided datasource.

Response definition

datasource_id uuid

  • The id of the datasource this response was created from

min integer

  • The smallest event_timestamp.

max integer

  • The largest event_timestamp.

time_in_usec integer

  • Time elapsed in the engine while generating the response

Examples

Request

POST /datasource/b43766b2-76d5-4a88-a9d6-0e8cd754da56/analyze

Body

{"data":{"method":"get_event_time_range"}}

Response

{"status":"ok","data":{"datasource_id":"b43766b2-76d5-4a88-a9d6-0e8cd754da56","min":0,"max":10799,"time_in_usec":58}}
POST /datasource/{datasource_id}/analyze

Route parameters

datasource_id string

  • The id of the datasource to retreive statistics from

Body parameters

event_timestamp integer

  • The timestamp of the event to view in the result set.

filter array [filter :: object]

  • The filter that should be applied to the result set.

columns array [column :: object]

  • The columns that should be included in the response.

Description

This API produces an integer value for the total number of keys matching the filter and event_timestamp provided, as well as individual counts for requested columns.

Response definition

datasource_id uuid

  • The id of the datasource this response was created from

Examples

Request

POST /datasource/b43766b2-76d5-4a88-a9d6-0e8cd754da56/analyze

Body

{"data":{"method":"get_statistics","event_timestamp":5,"columns":[{"column_id":"charging"},{"column_id":"make"},{"column_id":"model"},{"column_id":"fuel"}],"filter":{"logical":"and","conditions":[{"test":"match","column_id":"model","values":["Phantom","Matrice 100"]},{"test":"range","column_id":"fuel","from":0,"to":100000},{"test":"match","column_id":"charging","values":["Charging"]}]}}}

Response

{"status":"ok","data":{"datasource_id":"b43766b2-76d5-4a88-a9d6-0e8cd754da56","total":51,"stats":[{"column_id":"charging","result":{"Charging":51}},{"column_id":"make","result":{"Dajiang Innovation":51}},{"column_id":"model","result":{"Phantom":19,"Matrice 100":32}},{"column_id":"fuel","result":{"1043":1,"1044":1,"1054":1,"1103":1,"1112":1,"1128":1,"1198":1,"1234":2,"1326":1,"1333":1,"1368":1,"1423":1,"1427":1,"1466":1,"1484":1,"1525":1,"1567":1,"1569":1,"1590":1,"1618":1,"1644":1,"1770":1,"1786":1,"1796":1,"1903":1,"1983":1,"1995":1,"2004":1,"2043":1,"2167":1,"2179":1,"2209":1,"2300":1,"2322":1,"2346":1,"2355":1,"2564":1,"2595":1,"2604":1,"2731":1,"2767":1,"2780":1,"2811":1,"2846":1,"2897":1,"2945":1,"2951":1,"2956":1,"2978":1,"2991":1}}],"time_in_usec":17929}}

Overview

Analysis APIs are those that enable (real-time or historical) statistical, aggregational, and export workflows on previously added data.

Binary, plain text, and JSON responses

Depending on the method invoked, a successful response may take the form of binary data (as in the case of a compressed CSV from export_csv, or a PNG image from a tile request), JSON (as in invocations of get_statistics, export_json, or error responses from any analysis method), or plain text (as in an uncompressed CSV from export_csv). Consult the procedure documentation in Available APIs.

Shared keys

The following shared keys are present in multiple methods, and are described in more detail in their respective sections:

The filter key

These are composed one or more combinations of logical blocks and conditional blocks expressed as JSON that provide an interface for excluding or including subsets of a dataset. While optional, filter will almost always be present in useful method invocations.

Only boolean and is currently supported!

The example below shows the use of a logical or, as a means of illustrating how logical statements are combined. At this time, use of or in method invocations is not permitted. This restriction will be lifted in a future release.

Structure

The following is an example of a moderately complex filter definiton:

{"logical":"and","conditions":[{"test":"match","column_id":"model","with_undefined":true,"with_unknown":true,"values":["Phantom"]},{"test":"range","column_id":"fuel","from":42,"to":55},{"test":"range","column_id":"event_timestamp","from":531321545,"to":99999999999},{"logical":"or","conditions":[{"test":"match","column_id":"charging","value":["Discharging"]},{"test":"match","column_id":"make","value":["Matternet","Skycatch"]}]}]}

Logical blocks

These types of blocks are containers for conditional blocks, and specify how those conditions should be evaluated from a boolean perspective.

These properties are defined as follows:

logical

One of and or or, which specifies the boolean operation to perform on the provided conditions.

conditions

An array of conditional blocks that specify the parameters that must be satisfied in order to be included in the result set.

Logical and blocks

An and block requires that every specified condition evaluates to true in order for the logical and block to evaluate to true. The meaning of the properties of these blocks is described in the logical blocks section.

A logical and block is expressed in the following format:

{"logical":"and","conditions":[]}

Logical or blocks

An or block requires that at least one specified condition evaluates to true in order for the logical or block to evaluate to true.

A logical or block is expressed in the following format:

{"logical":"or","conditions":[]}

Conditional blocks

Any type of conditional block is expressed with the following properties and format:

{"test":"","column_id":"","with_undefined":true,"with_unknown":true}

These properties are defined as follows:

test

The specific comparison operation to perform. These comparators and additional properties they require for use are described in their associated section below. Valid comparators are:

  • match
  • range
  • geo_bounding_box
column_id

The column to apply the conditional block to. See for more detailed documentation.

with_undefined

Whether or not to include undefined values in the result set. See Null and undefined values for more documentation.

with_unknown

Whether or not to include null values in the result set. See Null and undefined values for more documentation.

Conditional match test blocks

These types of blocks are expressed in the following format:

{"test":"match","column_id":"","with_undefined":true,"with_unknown":true,"values":[]}

In addition to the properties inherited from the base conditional blocks, these block properties are defined as follows:

values

An array of one or more values to match against. If any of the given values match, the block evaluates to true.

Conditional range test blocks

These types of blocks are expressed in the following format:

{"test":"range","column_id":"","with_undefined":true,"with_unknown":true,"from":123456,"to":99999999}

In addition to the properties inherited from the base conditional blocks, these block properties are defined as follows:

from

The beginning of the range to include in the result set. Note that this is inclusive, which means that events with exact values matching the from value will be included.

to

The end of the range to include in the result set. Note that this is exclusive, which means that events with exact values matching the to value will not be included.


geo_bounding_box test blocks

These types of blocks are for specifying a geographic bounding box filter, and are expressed in the following format:

{"test":"geo_bounding_box","column_id":"","north":50,"south":44.5,"west":-123.05,"east":-121}

Note that this test type does not support with_unknown or with_undefined options.


The method key

A method is a remote procedure call. Various methods are available, and examples of each supported method can be found in the Available APIs section.

Note that for HTTP GET requests (such as the Display Tile API, the method is supplied on your behalf and may be omitted.


The event_timestamp key

This key represents a moment in time, and is described in more detail in the Event Timestamp section. It can be used with any method as a filtering mechanism, either by itself or in combination with any Filter.

Note: event_timestamp is mutually exclusive with event_timestamp_begin and event_timestamp_end.


The event_timestamp_begin and event_timestamp_end keys

These keys represent the inclusive start and exclusive end of a time range, respectively. While not required, if they appear in a method request both keys must be present. This key pair can be used with any method as a filtering mechanism, either by themsevles or in combination with any Filter.

Note: event_timestamp is mutually exclusive with event_timestamp_begin and event_timestamp_end.


Method-dependent keys

Additional parameters and options may be available for a given method. Consult the appropriate method documentation in the Available APIs section for more details.

Push

Overview

Push APIs are those that enable the streaming of new data (append), or the replacement of old data (update). The add_time_series_data and add_static_data APIs apply in real-time, with their updates being made immediately available for use with the Analysis APIs.

Available APIs

POST /datasource/{datasource_id}/push

Route parameters

datasource_id string

  • The id of the datasource to add static data to

Body parameters

data

  • An array of static tuple objects to add.
  • A static tuple consists of a 'key' array containing 1 or more valid key column types, and a 'columns' object containing key-value pairs to assign for this key.

Description

This API allows for the streaming of one or more tuples containing static data. Static data is appropriate for attributes that do not need a history of changes to those attributes persisted.

Response definition

datasource_id uuid

  • The id of the datasource this response was created from

time_in_usec integer

  • Time elapsed in the engine while generating the response

Examples

Request

POST /datasource/b43766b2-76d5-4a88-a9d6-0e8cd754da56/push

Body

{"data":{"method":"add_static_data","data":[{"key":["6f4d8fd0-ea25-11e5-9ce9-5e5517507c66"],"columns":{"make":"Dajiang Innovation","model":"Phantom"}}]}}

Response

{"status":"ok","data":{"datasource_id":"b43766b2-76d5-4a88-a9d6-0e8cd754da56","time_in_usec":40}}
POST /datasource/{datasource_id}/push

Route parameters

datasource_id string

  • The id of the datasource to add time series data to

Body parameters

data

  • An array of time series tuple objects to add.
  • A time series tuple consists of a 'key' array containing 1 or more valid key column types, an 'event_timestamp' > 0, and a 'columns' object containing key-value pairs to assign for this key.

Description

This API allows for the streaming of one or more tuples containing time series data. Timeseries data is appropriate for attributes for which a history of changes to those attributes should be kept for later analysis.

Response definition

datasource_id uuid

  • The id of the datasource this response was created from

time_in_usec integer

  • Time elapsed in the engine while generating the response

Examples

Request

POST /datasource/b43766b2-76d5-4a88-a9d6-0e8cd754da56/push

Body

{"data":{"method":"add_time_series_data","data":[{"key":["6f4d8fd0-ea25-11e5-9ce9-5e5517507c66"],"event_timestamp":100798,"columns":{"fuel":50000,"charging":"Discharging","lat":42.195969,"long":-94.625244}}]}}

Response

{"status":"ok","data":{"datasource_id":"b43766b2-76d5-4a88-a9d6-0e8cd754da56","time_in_usec":205}}

Shared keys

The following shared keys are present in multiple methods, and are described in more detail in their respective sections:

The key key

The key is an array of key values that are both valid key types and valid for the datasource schema used for the target datasource.

Order is important - entries in the key array must follow the order of the types specified in the datasource schema.

The columns key

An object containing key-value pairs that should be set for the key provided.

Key-value pairs provided must be method-appropriate.

It is an error to provide key-value pairs for columns defined as time_series_columns in an add_static_data method invocation, and vice-versa.

The event_timestamp key

For method invocations that have a temporal interface (such as add_time_series_data the event_timestamp is a required parameter specifying the moment in time to assign the provided columns values to a given key.

See the Event Timestamp section for more information about event_timestamp.

add_static_data does not honor this parameter!

Due to the behavior of add_static_data effectively "rewriting history" for any previously written value for a static column, event_timestamp has no meaning in this context.