CONDUIT HTTP API V6

[download_after_email id=”36017″]

Conduit is a service within the AlphaX Cloud architecture that allows HTTP clients to interact directly with the database. The Conduit feature adds a layer of security when importing and exporting data by adding a security token and server-side validation when passing data requests. It is activated per user on a service-by-service basis.

Services controlled by the conduit service include:

MQTT Service

Webhook Service

HTTP API service

This document will cover the HTTP API of the Conduit service

Authentication

You authenticate to the Alphax Cloud API by providing one of your security tokens in the X-Api-Key request header:

GET /conduitv6/

Host: app.alphax.cloud

X-Api-Key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxx (the Token may also be passed in the URI but is considered a less secure method)

SSL Security

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must provide a token for all requests.

Enabling the Conduit service

To activate conduit for one of your users (or yourself) log into the AlphaX system and follow the instructions below.

1. Navigate to People->Users in the main Navigation Menu

2. Select the user that Conduit should be enabled for.

3. Toggle the “Enable Conduit” Switch.

4. Click the Save button.

5. The Conduit Token ID: will be displayed for that user

NOTE: V6 Adds the ability to switch on/off individual layers of token security for MQTT, API and Webhook functionality.

See this article for help: https://minnovation.com.au/knowledge-base/how-to-enable-conduit-for-a-user/

HTTP Methods

The following HTTP methods are used to determine which action to take on a particular resource:

Method                               Action

GET                        “Get” data from resource

POST                     “POST” data to a resource

PUT                        Update a specific resource

DELETE                  Delete a specific resource

HTTP Headers

The following HTTP headers are used by the AlphaX conduit service:

Header Value                                                    Description

Token:xxxxxxx                                                  All requests must include a token

Content-Type: application/json                All requests containing JSON data in the body must specify this header

Content-Encoding: gzip                                 Request body is gzip compressed

Accept-Encoding: gzip                                    Response will use gzip compression when content-length > 1024               bytes

X-HTTP-Method-Override:PUT, DELETE Clients not supporting PUT/DELETE methods can send via POST with this header

HTTP Status Codes

The Conduit service will return appropriate HTTP status codes for every request.

Code                     Status                                   Description

200                         OK                                          Completed successfully

304                         Not Modified                     There was no new data to return

400                         Bad Request                      The request was invalid or cannot be otherwise served

401                         Unauthorized                    Authentication failed

403                         Forbidden                           No permission for HTTP Method or requested resource

404                         Requested resource not found  Requested resource not found

405                         Method Not Allowed      Resource does not support the requested HTTP Method

413                         Request Too Large           Request body or response exceeds limit

429                         Too Many Requests        Request has been rejected for exceeding usage limits

500                         Internal Server Error       Error occurred processing the request

503                         Service Unavailable         Service is temporarily unavailable

Error and Status messages

Error and Status messages are always returned in a standard JSON format with the status code and message in the body of the response. An example error response:

{“code”:”405″,”error”:”Method Not Allowed”}

Status messages are returned for certain requests that have been accepted but do not return a resource in the response body:

{“code”: 304, “error”: “Operation accepted but not yet complete”}}

HTTP Compression

HTTP compression is supported on both incoming and outgoing requests. Compression is highly recommended where large requests are being submitted.

We use the standard HTTP method of specifying compression encoding, with support for the gzip compression schema.

Incoming compression

In order to send compressed data to the AlphaX conduit service it is necessary to send it with gzip encoding. Compress your data using gzip and add the Content-Encoding header to your request:

Content-Encoding: gzip

Outgoing compression

To receive data from the AlphaX Conduit service in gzip compressed format simply add the Accept-Encoding header to your request:

Accept-Encoding: gzip

Any response exceeding 1024 bytes will be compressed and the Content-Encoding header added.

Resource Attributes

API Resource requests commonly result in a response containing the current representation of one or more resources. The representations are a combination of attributes used to describe the individual resources.

Consumers of Resources should tolerate the addition of new attributes and variance in ordering of attributes with ease. Not all attributes appear in all contexts. It is generally safe to consider a nulled attribute, an empty set, and the absence of an attribute as the same thing.

Attributes are assigned specific Data types which are enforced for all requests and include:

Request Arguments

Conduit requests allow for arguments to be specified as part of the request URL. While some resources have required arguments, most are optional and are used to alter, refine or filter the response.

Arguments are specified using the standard Query string format and should be appended to the resource endpoint, prefixed with a ‘?’.

https://app.alphax.cloud/conduitv6?token=xxxxxxxxxxxxxxxxxxxx&fcdt=1539792000&tcdt=1539840604

All special characters should be Url Encoded.

id [argument]: The network ID that is used to register and track the device in the AlphaX system. This parameter is optional, if not defined, you will get data values for all devices the user has site access to.

ch [argument]: The individual channel ID that is assigned within the AlphaX system. This parameter is optional, if not defined, you will get data values for all the channels of the requested devices.

fcdt [argument]: From Created Date Time, the starting range timestamp in seconds. This parameter is optional, if not defined, you will get data values of last one hour. This parameter definition requires ‘tcdt’ parameter definition to work as desired.

tcdt [argument]: To Created Date Time, the ending range timestamp in seconds. This parameter is optional, if not defined, you will get data values of last one hour. This parameter definition requires ‘fcdt’ parameter definition to work as desired.

Data Formats

Conduit uses JSON data format by default for all requests and responses.

Request

Content-Type must be defined in the header of all requests that contain data:

Content-Type: application/json

The body of the request must be valid JSON or a 400 Bad Request response will be returned. The complete HTTP request should not exceed 5MB before compression. A 413 Request Too Large response will be returned for requests exceeding the size limit.

Expected Response

Example response from a Conduit GET request. The conduit will contain a separate array for each data point as well as the device metadata:

https://app.alphax.cloud/conduitv6?id=70xxD5xxxxDC0xxx&ch=1&token=xxxxxxx84exdcxxxxxx17

HTTP/1.1 200 OK

Content-Length: 831

Content-Type: application/json; charset=utf-8

[

    {

        “val_date”: 1614054737,

        “dev_netid”: “70B3D54990DC01DA”,

        “dev_chid”: 1,

        “val_raw”: 4.091,

        “val_type”: “Voltage”,

        “dev_tag”: “MIT-GW06 Pyalong Reserve”,

        “val_description”: “Battery Bank A”,

        “dev_site”: “Minnovation”,

        “val_cal”: 0,

        “val_offset”: 0,

        “dev_error”: 0,

        “dev_type”: “device”,

        “dev_label”: “Active”,

        “dev_category”: “Device”,

        “dev_powersource”: “Solar”,

        “dev_manufacturer”: “Minnovation”,

        “dev_supplier”: “Minnovation”,

        “dev_model”: “X1 Analog to Digital Sensor”,

        “dev_serial”: “70B3D54990DC01DA”,

        “dev_network”: “The Things Network”,

        “loc_lat”: 49.610711,

        “loc_lng”: 8.789063,

        “val_calibrated”: 4.091

    }

]

Network ID

Nodes must be accessed with their networkID. This is the same unique id that identifies the device regardless of it’s network type.

Versioning

The conduit version number is specified as part of the URL and appended to the conduit command. V6 is the currently supported version and has a base URL:

https://app.alphax.cloud/conduitv6/

Datapoint Limit

The conduit service has the limit of 10,000 datapoints at a time i.e. the json response will be the array of maximum 10,000 elements only. If your need to access more than 10,000 datapoints, try requesting multiple times with short time ranges, or by multiple ‘id’ and/or ‘ch’ query parameters.

Usage Throttling

The conduit service is throttled by default. One request is allowed every 15 seconds. We  recommend requesting one large amount of data rather than many small requests. Requests that exceed this limit will receive a 429 Too Many Requests response.