CloudTables provides a REST API that can be used to embed data sets into a HTML page and retrieve data from CloudTables.
The documentation below details the REST URLs, options and returned data - this is the raw implementation which can be used with any server-side environment that can make HTTP requests. We also provide API tool kits for a number of server-side environments that wrap this API into an easy to use package using paradigms suitable for that environment. For full details, please refer to the documentation for each library:
Rate limits
Please note that we apply a rate limiter to our API. This is currently 500 requests over a a 15 minute period. If you require more than this, please get in touch.
POST https://sub-domain.cloudtables.io/api/1/access
Get an access token that can be used to securely embed a CloudTable into an HTML page.
Body parameters:
Name | Required | Type | Description |
---|---|---|---|
key |
Required | String | The API key which will allow access (and thus assign the roles that can be used for access). |
clientId |
Optional | Any | A unique id for the client accessing the table on your system. While this is optional it is a recommended parameter as it is useful for tracking requests in CloudTables' analytics. |
clientName |
Optional | String | A label that can help identify a user - e.g. a name or e-mail address. Typically the clientId will be an integer or UUID which mean you'd need to look up the user to understand who made what changes. Note that while the clientId should be unique per client and not change - the clientName can change and will be updated to reflect the latest value given (e.g. if a user modifies their name in your own system). |
conditions |
Optional | Array or Object | Conditions to apply to the accessed data. Only data meeting the requirements will be returned. Please see the conditional data access documentation for full details. |
duration |
Optional | Integer | Access token's time to first use, or idle time out in seconds. If there are no actions after the given period of time the access rights of the token will be revoked and a new token would be required to carry on. Note that a web-page using a token will retain the access granted to it while the page is open. Defaults to 20 minutes. |
role |
Optional | String | The name of the role that should be used for the generated access token (if assigned to the API key - if the role is not available for the API key no access will be granted). If not provided then all roles available to the API key will be used. |
roles |
Optional | String[] | Similar to role but allows multiple roles to be specified. |
Response:
JSON object with the following parameters:
Name | Type | Description |
---|---|---|
token |
String | The access token that can be used in the embed <script> request. See the embed documentation. |
GET https://sub-domain.cloudtables.io/api/1/datasets
Get a list of all data sets which can be accessed by the role(s) available to this API key and summary information about each data set.
Query parameters:
Name | Required | Type | Description |
---|---|---|---|
key |
Required | String | The API key which will allow access (and thus assign the roles that can be used for access). |
role |
Optional | String | The name of the role that should be used (if the role is not available for the API key no access will be granted). If not provided then all roles available to the API key will be used. |
roles |
Optional | String[] | Similar to role but allows multiple roles to be specified. |
Response:
JSON object with the following parameters:
Name | Type | Description |
---|---|---|
datasets |
Array | Information about the accessible data sets. |
datasets[].deleteCount |
Integer | Number of rows deleted from the data set. |
datasets[].id |
String | ID of the data set. |
datasets[].insertCount |
Integer | Number of rows that have been inserted into the data set. |
datasets[].lastData |
ISO8601 | Date / time of the last create, update or delete on the data set. |
datasets[].name |
String | Name of the data set |
datasets[].readCount |
Integer | Number of times the data set has been read. |
datasets[].rowCount |
Integer | Number of rows that are currently in the data set. |
datasets[].updateCount |
Integer | Number of update operations on the data set. |
GET https://sub-domain.cloudtables.io/api/1/dataset/{id}/data
Get the data for a specified data set, where {id}
in the URL is the data set id, per the /datasets
API. The data set ID can also be found in the Data set inspector of the Data tab for the data set.
Query parameters:
Name | Required | Type | Description |
---|---|---|---|
key |
Required | String | The API key which will allow access (and thus assign the roles that can be used for access). |
role |
Optional | String | The name of the role that should be used (if the role is not available for the API key no access will be granted). If not provided then all roles available to the API key will be used. |
roles |
Optional | String[] | Similar to role but allows multiple roles to be specified. |
Response:
JSON object with the following parameters:
Name | Type | Description |
---|---|---|
columns |
Array | Information about the columns of data. |
columns[].id |
String | Column ID. This will have the prefix c- for computed values and dp- for data points, each followed by a unique number. |
columns[].link |
String | If the data point is from a linked data set, this is ID for the link (it will have the prefix l- ). Otherwise, it will be null if not from a linked data set. |
columns[].name |
String | Defined name for the column. |
data |
Array | The data for the data set. |
data[].id |
Integer | ID of the row. |
data[].dv |
Integer | Data version of the row. |
data[].* |
See below | Data for the row where * is the id of the matching column. If representing a linked column the value will be an array of objects for the link data points and calculated value, while the name will match the link id. |
Please note that at this time the following formatting is used for the various data types:
date
- ISO 8601 (date only)datetime
- ISO 8601number
- Unformatted numbertext
- Plain texttime
- ISO 8601 (time only).