Best Practices¶

Enforce Security¶

All requests must be made over HTTPS.

API keys should be kept secret and the Read only permission assigned to keys that only need to perform read operations (GET requests). For additional security, you can restrict the API key to certain Workspaces by setting the Access level to Limited Workspaces.

Use Compression for large requests¶

Take advantage of HTTP compression for sending and receiving large requests.

Limit Size and Rate of requests¶

When working with time series data, ensure you limit the size of the requests for both extraction and insertion. If the request or response is too large or exceeds our processing time threshold, the 413 Request Too Large error response will be returned.

The body of the request should not exceed 5MB before compression. The query string should not exceed 4096 bytes. A 413 Request Too Large response will be returned for requests exceeding the size limit.

You should limit the rate of requests to the API to ensure you do not exceed the usage limits.

Handle Errors and Status responses¶

Responses will always use HTTP Status Codes to indicate the result of the request. Be prepared to handle unexpected errors which may arise from:

• Large or long running requests
• Moved, renamed or deleted resources
• API key permission and account changes
• Usage limits exceeded
• Service temporarily unavailable

Discover Node Ids from the user interface¶

Node Ids are shown in the associated Node properties dialog. You can also assign your own unique Custom Id to every node for use with the API.

Use Development Tools for testing¶

Use development tools such as cURL or Postman to test API requests and responses. We recommend Postman for its simple to use, powerful user interface.

Synchronise data efficiently¶

When synchronising data to an external system, ensure you only query for data that has changed since your previous request. By specifying a timeQuery of MODIFIED, only records added or changed within your query range will be returned.