NodeJS API

If you are working with a NodeJS environment we provide an NPM package that provides library functions to make interacting with the CloudTables API as simple as a class constructor and method call. Using the library you can easily embed data sets securely into your pages, get information about data sets and the data of a specified dataset.

Installing

The CloudTables libraries are available as the cloudtables-api package on npm and can be installed for your project using:

# npm
npm install --save cloudtables-api
# yarn
yarn add cloudtables-api

Use

The CloudTables API libraries are written in TypeScript, so if you are using TypeScript you can import the library and get the full benefits of strict typing using (note that this will also work with ES6 modules in NodeJS >= v13):

import CloudTablesApi from 'cloudtables-api';

For versions of NodeJS older than v13, you can import the libraries using require:

const CloudTablesApi = require('cloudtables-api').default;

Initialisation

Once imported into your application, you need to create an API instance so the methods it provides can be configured and accessed. This can be done using:

let api = new CloudTablesApi('sub-domain', '{apiKey}', {
	clientId: 'Unique client id', // Client id (e.g. a login id) - optional
	clientName: 'Name'            // Client's name - optional
});

Where:

  • {apiKey} should be replaced by the API key that you want to use for the access.
  • clientId and clientName in the configuration object are optional, but we strongly recommend they are used when integrating with your own login system as it allows the identification of each client's actions in CloudTables' auditing features. Typically the clientId would be set to your login system's user id and clientName the user's username or full name.

A new CloudTablesApi instance should be created for each access request, as it will cache and reuse the access token if one is required.

Embedding data sets

There are three methods provided by the library which can be used to embed a data set into your HTML page. The end result is a <script> tag which includes an access token. That can then be inserted into your HTML using a variable, a handlebars template or another method depending on how you are generating your HTML.

Fully automatic script tag

The scriptTagAsync method can be used to get an access token (based on the initialisation options) for a data set, and will return a string that contains the full <script> tag that should be inserted into your HTML:

let script = await api.scriptTagAsync('{data-set-id}');

Where:

  • {data-set-id} is the ID of the data set you wish to embed into the page. The data set ID can be found in the Inspector for the data set on the Data tab.

Note that we use await here as the function returns a Promise. This means it needs to be in an async function.

Automatic script tag with token

If you wish to generate an access token first and then use it synchronously you can do so using:

let token = await api.token();
let script = api.scriptTag(token, '{data-set-id}');

Custom script tag

Finally, you can also build your own <script> tag based on a token:

let token = await api.token();
let script = `
	<script
		src="https://sub-domain.cloudtables.io/loader/{data-set-id}/table/d"
		data-token="${token}"
	></script>
`;

API Reference

Constructor

new CloudTablesApi(subdomain: string, key: string, options?: IOptions)

Creates a new instance of the CloudTables API libraries.

  • Parameters:
    1. subdomain - The application sub-domain for your CloudTables (i.e. the part before .cloudtables.com).
    2. key - The API key to be used
    3. options - Object of optional parameters:
      • clientId: string - 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: string - A label that can help identify a user - e.g. a name or e-mail address.
      • conditions: array | object - Condition(s) to apply to data being fetched. Please see the embedding conditions documentation for full details. Requires cloudtables-api 1.1 or newer.
      • duration: number - Access token’s idle time out (defaults to 20 minutes).
      • roles: 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.
      • role: string - Per roles but for a single role only.
      • secure: boolean - Disallow (true), or allow (false) self-signed certificates
      • ssl: boolean - Enable (true), or disable (false) SSL / HTTPS
  • Returns: API instance

Methods

data

Get the data and columns for a given dataset.

.data(dataset: string): Promise<IDatasetData>
  • Async: Yes
  • Parameters:
    1. dataset - ID of the data set to get the data of. See the Data page for the data set to get its ID, or use the .datasets() method.
  • Returns: Object containing data and columns arrays. Please refer to the API documentation for a full description of the structure returned.

datasets

Get summary information about the available datasets (note that the roles applied in the constructor can restrict access so certain data sets will not be shown).

.datasets(): Promise<IDatasetInfo[]>
  • Async: Yes
  • Returns: Array containing information about the available data sets. Please refer to the API documentation for a full description of the structure returned.

scriptTag

Get a <script> tag for a specific dataset to be displayed as a table. Insert this script tag where you want the table to appear in your HTML.

.scriptTag(token: string, dataset: string, style: IStyleFramework = 'd'): string
  • Async: No
  • Parameters:
    1. token - Secure access token (from .token())
    2. dataset - ID (UUID) of the dataset to be shown
    3. style - The styling framework to use for this table. Can be one of:
      • d - Default
      • auto - Auto detect
      • bs - Bootstrap 3
      • bs4 - Bootstrap 4
      • dt - CloudTables / DataTables default styling
      • zf - Zurb Foundation
      • ju - jQuery UI
      • se - Semantic UI
      • no - No styling
  • Returns: <script> tag to use.

scriptTagAsync

Get a <script> tag for a specific dataset to be displayed as a table. Insert this script tag where you want the table to appear in your HTML. This is the same as scriptTag, but it will retrieve the secure access token for you - thus requiring it to be async.

scriptTagAsync(dataset: string, style: IStyleFramework = 'd'): Promise<string>
  • Async: Yes
  • Parameters:
    1. dataset - ID (UUID) of the dataset to be shown
    2. style - The styling framework to use for this table. See the scriptTag method for valid values.
  • Returns: <script> tag to use.

token

Get an access token. Note that this value is cached per API instance. It will only be obtained from the CloudTables server's once.

.token(): Promise<string>
  • Async: Yes
  • Returns: Access token to be used with the <script> tag to access a data set.

Source

Our API libraries for CloudTables are open source under the MIT license. The NodeJS source is available here and pull requests or suggestions for it are welcome.