.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("sub-domain", "{apikey}")
	.ClientId("Unique client id")
	.ClientName("Name");

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.

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.ScriptTag("{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 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 = [email protected]"
	<script
		src=""https://sub-domain.cloudtables.io/loader/{data-set-id}/table/d""
		data-token=""{token}""
	></script>
";

Api class reference

The CloudTables.Api class is used to directly interface with the CloudTables API, including requesting access tokens and retrieving data from a data set.

Constructor

Creates a new instance of the CloudTables API libraries.

new Api(string subdomain, string key)
  • Namespace: CloudTables
  • Parameters:
    1. string - The application sub-domain for your CloudTables (i.e. the part before .cloudtables.com).
    2. string - The API key to be used

API methods

Methods which map directly to CloudTables API methods. Note that these are all async functions since they require an external HTTP request to the CloudTables servers.

Data

Get the data and columns for a given dataset.

async Task<TypeDatasetData> Data(string id)
  • Parameters:
    1. string - ID of the data set to get the data of. See the Data tab 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).

async Task<TypeDatasets> Datasets()
  • 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.

async Task<string> ScriptTag(string id, string style = "d")
  • Parameters:
    1. dataset: string - ID (UUID) of the dataset to be shown
    2. style: string - 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.

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.

async Task<string> Token()
  • Returns: Access token to be used with the <script> tag to access a data set.

Configuration methods

Methods used to configure the Api instance for access.

ClientId

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.

Api ClientId(string value)
  • Parameters:
    1. string value - Client ID to use.
  • Returns this for chaining.

ClientName

A label that can help identify a user - e.g. a name or e-mail address.

Api ClientName(string value)
  • Parameters:
    1. string value - Client name to use.
  • Returns this for chaining.

Condition

Condition(s) to apply to data being fetched. Please see the embedding conditions documentation for full details. Requires Cloudtables.Api 1.1 or newer. Note that this method can be called multiple times to add additional conditions to the access request. They will then be combined with AND logic.

Please see below for a full description of the CloudTables.Condition class and its methods.

Api Condition(Condition cond)
  • Parameters:
    1. Condition cond - Condition to apply to the data access.
  • Returns this for chaining.

Domain

Host domain for the CloudTables instance. Used for self-hosted installs of CloudTables.

Api Domain(string value)
  • Parameters:
    1. string value - Domain name or IP address.
  • Returns this for chaining.

Duration

Access token’s idle time out (defaults to 20 minutes).

Api Duration(int value)
  • Parameters:
    1. int value - Idle time out value (seconds).
  • Returns this for chaining.

Role

Per Roles but for a single role only.

Api Role(string value)
  • Parameters:
    1. string value - role to assign.
  • Returns this for chaining.

Roles

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.

Api Roles(IEnumerable<string> value)
  • Parameters:
    1. IEnumerable<string> value - roles to assign.
  • Returns this for chaining.

Ssl

Use https or http connections. Used for self-hosted installs of CloudTables.

Api Ssl(boolean value)
  • Parameters:
    1. boolean value - SSL flag
  • Returns this for chaining.

Condition class reference

Constructors

Creates a new condition instance which can be applied to a data access request, limiting the data that will be returned by the server. See the embedding conditions documentation for full details.

new Condition()
new Condition(string id, string value)
  • Namespace: CloudTables
  • Parameters:
    1. string - The id of the data point the condition should be applied to.
    2. string - The value to use.

Methods

Id

Set the id of the data point to perform the condition on. The ids can be found from your data set's Data page and click on the item in question. The id will be shown in the item inspector on the right. It will start dp- for a regular data point. Conditions on computed values (c-) and links (l-) are not currently supported.

Condition Id(string id)
  • Parameters:
    1. string id - The id of the data point to perform the condition on.
  • Returns this for chaining.

Name

Set the name of the data point to perform the condition on. This can be given as an alternative to the id option as it is easier to remember. However, while the id is static, the name can be changed in the application.

Condition Name(string name)
  • Parameters:
    1. string id - The data point's name that the condition should be performed upon.
  • Returns this for chaining.

Op

Set the conditional operator.

Condition Op(string op)
  • Parameters:
    1. string op - Conditional operator - it may be one of =, !=, <, <=, >=, >.
  • Returns this for chaining.

Set

Mark the value to be set (default) or not when creating a new row.

Condition Set(bool set)
  • Parameters:
    1. bool set - When a new record is created, the API can set the data point to a specific value (defined by setValue or value if the former is not specified).
  • Returns this for chaining.

SetValue

The value that will be written to the database if Set is enabled. Note that Value will be used by default, and this method can override it with a new value to be set. It must be specified if Op is not set to =.

Condition SetValue(string setValue)
  • Parameters:
    1. string setValue - Value to set when a new record is created.
  • Returns this for chaining.

Value

The value that will be used for the conditional matching, and for writing to new records, unless SetValue is specified. The formatting must follow these rules:

  • date - ISO 8601 (date only)
  • datetime - ISO 8601
  • number - Unformatted number
  • text - Plain text
  • time - ISO 8601 (time only).
Condition Value(string value)
  • Parameters:
    1. string Value - Value to set when a new record is created.
  • Returns this for chaining.

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.