Python API

If you are working with a Python environment we provide a PyPI package that makes interacting with the CloudTables API as simple as calling a class constructor and then the method. 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 library is available as the CloudTablesApi package on PyPi and can be installed for your project using:

# pip
pip install CloudTablesApi

# python
python3 -m pip uninstall CloudTablesApi

Use

The CloudTables API libraries provide a class whose constructor returns an API handle.

from CloudTablesApi import CloudTablesApi

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:

api = CloudTablesApi('{apiKey}', options={
	clientId: 'Unique client id', # Client id (e.g. a login id) - optional
	clientName: 'Name',           # Client's name - optional
	domain: '{ip-or-hostname}'    # Your CloudTables host
})

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.

• {ip-or-hostname} is the access address configured for your CloudTables install.

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 two methods provided by the library 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.

Fully automatic script tag

The dataset().script_tag() 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:

token = api.token()
script = api.dataset('{data-set-id}').script_tag(token)

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.

Custom script tag

You can also build your own <script> tag based on a token:

token = api.token()
script = (
	"<script "
	"src='https://ip-or-hostname/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().script_tag()
    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.
  • .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 Python source is available here and pull requests or suggestions for it are welcome.