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.
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" />
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.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.
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.
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
.
Alternatively, you can also build your own <script>
tag based on a token:
var token = await api.Token();
var script = $@"
<script
src=""https://sub-domain.cloudtables.io/loader/{data-set-id}/table/d""
data-token=""{token}""
></script>
";
The CloudTables.Api
class is used to directly interface with the CloudTables API, including requesting access tokens and retrieving data from a data set.
Creates a new instance of the CloudTables API libraries.
new Api(string subdomain, string key)
string
- The application sub-domain for your CloudTables (i.e. the part before .cloudtables.com
).string
- The API key to be usedMethods 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.
Get the data and columns for a given dataset.
async Task<TypeDatasetData> Data(string id)
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.data
and columns
arrays. Please refer to the API documentation for a full description of the structure returned.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()
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")
dataset: string
- ID (UUID) of the dataset to be shownstyle: string
- The styling framework to use for this table. Can be one of:
d
- Defaultauto
- Auto detectbs
- Bootstrap 3bs4
- Bootstrap 4dt
- CloudTables / DataTables default stylingzf
- Zurb Foundationju
- jQuery UIse
- Semantic UIno
- No styling<script>
tag to use.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()
<script>
tag to access a data set.Methods used to configure the Api instance for access.
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)
string value
- Client ID to use.this
for chaining.A label that can help identify a user - e.g. a name or e-mail address.
Api ClientName(string value)
string value
- Client name to use.this
for chaining.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)
Condition cond
- Condition to apply to the data access.this
for chaining.Host domain for the CloudTables instance. Used for self-hosted installs of CloudTables.
Api Domain(string value)
string value
- Domain name or IP address.this
for chaining.Access token’s idle time out (defaults to 20 minutes).
Api Duration(int value)
int value
- Idle time out value (seconds).this
for chaining.Per Roles
but for a single role only.
Api Role(string value)
string value
- role to assign.this
for chaining.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)
IEnumerable<string> value
- roles to assign.this
for chaining.Use https
or http
connections. Used for self-hosted installs of CloudTables.
Api Ssl(boolean value)
boolean value
- SSL flagthis
for chaining.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)
string
- The id of the data point the condition should be applied to.string
- The value to use.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)
string id
- The id of the data point to perform the condition on.this
for chaining.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)
string id
- The data point's name that the condition should be performed upon.this
for chaining.Set the conditional operator.
Condition Op(string op)
string op
- Conditional operator - it may be one of =
, !=
, <
, <=
, >=
, >
.this
for chaining.Mark the value to be set (default) or not when creating a new row.
Condition Set(bool set)
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).this
for chaining.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)
string setValue
- Value to set when a new record is created.this
for chaining.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 8601number
- Unformatted numbertext
- Plain texttime
- ISO 8601 (time only).Condition Value(string value)
string Value
- Value to set when a new record is created.this
for chaining.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.