HTTP Export Task (for Developers)

Introduction

The Export Tasks are used to retrieve raw (i.e. pre-processed) data from the backend servers. Therefore, some values in the Export Task data fields (e.g. Asset Odometers, Analog values) may differ on the UI to the raw value. For example, the odometer value in the export task may be from the device (odometer), or a counter value (odo_counter), not the asset value. This, plus any other value in the Export Task, should be compensated with offsets/calculations for from the Export Task raw data.

When a GET is performed, the data is removed automatically from the queue. However, if a DEL is not sent, the data will be sent again after a couple of minutes. 

When a DEL is performed, the data is permanently removed from the queue.

If data is not available, or the incorrect reference/ID is used, a "500" error will be returned. The task uses a long poll process, and if there is no data in the queue, will wait up to 45s before responding. If data is added to the queue during the delay, this will be sent out before the end of the 45s. If there is no data within 45s, then a 500 error is returned.

Documentation

The developer documentation detailing each request and response for the API is available at https://export.us1.kt1.io/docs/.

Authentication

The API key must be sent with every request as either a query parameter or a HTTP header.

Query Parameter (token)

A query parameter called token must be added containing the API key.

HTTP Header (x-access-token)

A header must be added called x-access-token containing the API key.

Retrieving Data

The first step to retrieve data from the API is to perform a GET operation. If there is data available in the queue of the HTTP Export Task, it will be returned in the response. If an id is present in the response, this should be used with the DELETE operation to remove the processed data from the queue.

If the DELETE operation is not issued within 2min of the corresponding GET, the data will be added back to the queue and will be available for subsequent GET operations.

Additional Options

Compression

The HTTP Export Task supports gzip compression of its responses. This can be enabled by adding the 'accept-encoding' header to the request.

Keep alive

The HTTP Export task supports HTTP Keep-alive allowing for subsequent queries to be significantly faster as existing connections are reused. This can be enabled by adding the 'connection' header to the request. This must be used in conjunction with a client that supports the reuse of HTTP connections.

Examples

The following are examples of using and deleting data with curl:

curl --request GET \

    --url 'https://exporttaskdomain/v2/stream/ \'

    --header 'x-access-token: KeyProvidedToken'

curl --request DELETE \

  --url https://exporttaskdomain/v2/stream/{GET_response.id}\

  --header 'x-access-token: KeyProvid