Embedding CloudTables

The whole point of CloudTables is to let you quickly and easily define the structure of your data and then embed it seamlessly into your own web application / page. As such we have two methods that can be used to perform the embedding:

  • Securely with server-side API key
  • With an API key client-side

Note that it is possible to use both methods of access for a single data set - which one is the most appropriate will depend upon the context. For example, you might wish to publish a table as read only available to the general public without needing to use a sever-side action, while still having full read / write access in your own admin portal.

Securely with server-side API key

The recommended way to embed a CloudTable in your application is to request an access token based on an API key. That access token gives the same access rights as the API key, but it is time limited and is available for use by one client session only. Any other clients attempting to access the embedded table using the same code would receive an access error.

The best way to get an access token is through one of our supported libraries - please see the documentation for the platform you are using. Here we will discuss the HTTP REST request needed only, as this can be readily implemented in any platform that can make an HTTP request.

An access token is requested by making a POST request to:

https://sub-domain.cloudtables.io/api/1/access

The following parameters can be used (please see the API documentation documentation for full details on the parameters that can be used and the response):

  • key (required) - the API key which will allow access (and thus assign the roles that can be used for access).
  • clientId - a unique id for the client accessing the table on your system. This is optional, but useful for tracking requests in CloudTables' analytics.
  • clientName - a label that can help identify a user - e.g. a name or e-mail address. Typically the clientId will be an integer or UUID which mean you'd need to look up the user to understand who made what changes. This parameter is also optional.

The CloudTables server will respond with a JSON string that has a token parameter. That value is the access token that can be used with a <script> tag to embed the CloudTable:

<script
	src="https://sub-domain.cloudtables.io/loader/{datasetId}/table/d"
	data-token="{accessToken}"
></script>

where:

  • {datasetId} - the ID of the data set you'd like to show (see the data set Embed tab for this information)
  • {accessToken} is the access token retrieved from the above HTTP request.

The <script> tag should be inserted into your HTML where you want the CloudTable to be shown.

With an API key client-side (Serverless)

This method will expose your API key in web-browsers and as such should not be used for sensitive data or with an API key that has write access in a context where you do not want to expose that functionality.

Having given you that warning, the advantage of using this method to embed a table is that it is very easy. You can place it directly into HTML without need for any server-side script contacting CloudTables before serving the client's request.

To embed the data set in your HTML page where you want the CloudTable to appear use:

<script
	src="https://sub-domain.cloudtables.io/loader/{datasetId}/table/d"
	data-apiKey="{apiKey}"
	data-clientId="{clientId}"
></script>

where:

  • {datasetId} - the ID of the data set you'd like to show (see the data set Embed tab for this information)
  • {apiKey} - the API key which will allow access (and thus assign the roles that can be used for access).
  • {clientId} - a unique id for the client accessing the table on your system. This is optional, but useful for tracking requests in CloudTables' analytics. For example you might use web as the id if you embed it in a public web-page, or an id specific to that page. A data-clientName parameter can also be specified, but that is more useful for the server-side API key interaction detailed above when you are using a user login system.