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, the data of a dataset, and also add, edit and delete data in a data set.

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 (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 dataset().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.dataset('{data-set-id}').scriptTagAsync();

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.dataset('{data-set-id}').scriptTag(token);

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

• new CloudTablesApi()
  Create a new CloudTablesApi instance.
  • .dataset()
    Get an object that can be used to retrieve information about and manipulate a data set.
  • .dataset().data()
    Get the data for a given dataset.
  • .dataset().insert()
    Insert new data into a data set.
  • .dataset().row()
    Get an object that can be used to retrieve information about and manipulate a specific row in the data set.
  • .dataset().row().data()
    Get the data for the selected row.
  • .dataset().row().delete()
    Delete the selected row.
  • .dataset().row().update()
    Modify the data of the selected row.
  • dataset().schema()
    Get information about the structure of a data set, including the name of the data points available in it.
  • dataset().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.
  • .dataset().scriptTagAsync()
    Async version of .dataset().scriptTag().
  • .datasets()
    Get summary information about the available datasets.
  • .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.

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.