.NET API

If you are working in .NET (Framework or Core) we provide a Nuget 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 Nuget and can be installed using your package manager:

# Package Manager
Install-Package CloudTables.Api

# .NET CLI
dotnet add package CloudTables.Api

<!-- Package reference in your project file -->
<PackageReference Include="CloudTables.Api" />

Initialisation

Once imported into your application, an instance can be created using:

using CloudTables;

var api = new Api("{apikey}")
	.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
	.Ssl(false);                  // Optional - disable SSL (https)

Where:

• {apikey} should be replaced by the API key that you want to use for the access.
• The ClientId and ClientName methods 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 Api 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 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.

Automatic script tag

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

var script = await api.Dataset("{data-set-id}").ScriptTag();

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 method is async and returns a Task.

Custom script tag

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

var token = await api.Token();
var script = $@"
	<script
		src=""https://ip-or-hostname/io/loader/{data-set-id}/table/d""
		data-token=""{token}""
	></script>
";

Demonstration video

In the following video Colin walks through a demonstration of installing and using the CloudTables .NET library. Please note there is a graphical glitch in the recording about 2m 30s in - apologies for this. There is nothing critical for the tutorial when that happens.

API Reference

• new CloudTablesApi()
  Create a new CloudTablesApi instance.
  • .Condition()
    Apply a condition to the data that can be fetched or set.
  • .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.

The Api class also has a number of configuration methods available to control how it accesses the CloudTables API.

Source

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