English
home app about

API Quick Start Guide

Note: Ardexa hosts clouds in multiple regions as subdomains of ardexa.com. Where you see a reference to mycloud in this document, replace it with the appropriate subdomain for your cloud, eg: mycloud.ardexa.com -> app.ardexa.com or eur1.ardexa.com

Quick start guide

This guide will cover reading data from any workgroup using the RESTful Ardexa API. This quick start guide should be enough to get you started, but for an in depth look at our API, please browse our online documentation: http://docs.ardexa.apiary.io/

Test environment

There are two main ways we recommend to quickly get started using our API:

  • The command line

    • Windows, OSX and Linux all support the use of command line tools such as “curl” (a tool for working with web services) and “jq” (a tool for working with JSON). All of the commands in this guide are run using a Linux command line, but should work equally well on Windows (extra tools will be required) or OSX.

  • Postman (Chrome Web Store)

    • We highly recommend a tool called Postman from the Chrome Web Store (works with Chrome or Chromium). We use this tool internally to test API configurations and tokens.

    • If you would like to use this tool, we have attached to this article a pre-configured workspace for you to import into Postman. It will help you to rapidly build your understanding of the API using a convenient, easy-to-use graphical interface.

Step one – Authentication

For authentication, we use JSON Web Tokens (JWT). These tokens are passed as part of the header for all requests to the API. As the TOKEN is a long string, we will store it in a variable for future use. Wherever you see $TOKEN it will be replaced with the actual authentication string. For example:

TOKEN=eyJhbGciOiKaOyr...

Most TOKENs have permissions to READ information about devices and perform SEARCHES. Please keep it somewhere safe and DO NOT share it. By default, these TOKENs expire after two months, but long term security tokens will be issued once all parties are satisfied with the process and privileges.

Step two – Getting data

But before we can fetch data, you will need to know your Workgroup ID. Your Workgroup ID can be found by browsing to Admin -> Workgroup.

The three key sections when getting started are:

Tables

Getting a list of tables is easy:

curl -s -H "Authorization: Bearer $TOKEN" https://[mycloud].ardexa.com/api/v1/tables/$WORKGROUP_ID | jq

This will return an array of table names. Once you’ve select the table you wish to query, e.g. table_name, you can get more information by querying the Table Info:

curl -s -H "Authorization: Bearer $TOKEN" https://[mycloud].ardexa.com/api/v1/tables/$WORKGROUP_ID/table_name | jq

This will return an object detailing the fields, their type, any units.

Simple search

Run the following command to see the latest 50 readings in table_name:

curl -s -H "Authorization: Bearer $TOKEN" https://[mycloud].ardexa.com/api/v1/tables/$WORKGROUP_ID/table_name/search?sort=-event_time | jq

You’ll notice the output contains an array of entries from table_name. Each record contains EVENT_TIME, DEVICE and SOURCE. EVENT_TIME is the timestamp that the agent picked up the given message and will always be UTC.

Timestamps

On some devices monitored by Ardexa, instead of giving a raw reading, they will instead provide a cached value and the time this cached value was recorded will be logged as DATETIME. We log exactly what was provided by the device.

Therefore, if DATETIME is present, this is the actual time the measurement was taken and EVENT_TIME is when the agent retrieved the reading and sent it to the cloud.

Device names

The DEVICE field is actually the device’s ID. To get a lookup table of Device Names, you’ll need to run the following command:

curl -s -H "Authorization: Bearer $TOKEN" https://[mycloud].ardexa.com/api/v1/devices/$WORKGROUP_ID | jq -r '.[] | "\(.id): \(.name)"'

Step three – Searching and filtering

The in-depth look at the SEARCH feature with examples is provided here.

Parameter handling

Generally speaking, depending on the framework or application you are using, you shouldn't have to worry about these specific implementation details like URL encoding and listing query parameters multiple times. Instead you should be able to simply pass in an Array of Objects and the framework will handle the rest (including parsing the JSON response).

However, for the sake of clarity, here are the details on how to handle some common data types.

Dates

Date fields will accept any ISO 8601 compliant date and time string.

Arrays

When passing arrays to an API, you simply repeat the target field, e.g. to only report the fields "device" and "event_time", you would send the following parameters:

?sort=-event_time&row=20&fields=device&fields=event_time

You can keep adding as many of the target field as necessary.

Objects

To use Objects as part of the query, you will need to serialize and encode the object for use as part of a URL

Example

Filters are an Array of Objects of the form: source, operator, value. You can get a list of operators, and what they expect in the value field, from the documentation: http://docs.ardexa.apiary.io/#reference/search/search/perform-a-search.

Let's say I want to use the following filter (keeping in mind that all filters are AND based to keep the API as simple as possible), which is an Array of Objects, with a Date as part of the filter:

[
{
  "field": "event_time",
  "operator": ">=",
  "value": "2017-07-12T00:00:00Z"
},
{
  "field": "source",
  "operator": "=",
  "value": "inverter-01"
}
]

This filter translates into the following search request:

https://[mycloud].ardexa.com/api/v1/tables/$WORKGROUP_ID/table_name/search?filters=%7B%22field%22%3A%22event_time%22%2C%22operator%22%3A%22%3E%3D%22%2C%22value%22%3A%222017-07-12T12%3A00%3A00Z%22%7D&filters=%7B%22field%22%3A%22source%22%2C%22operator%22%3A%22=%22%2C%22value%22%3A%22inverter-01%22%7D

Curl has an inbuilt feature to encode the filters

curl -G -H "authorization: bearer $TOKEN" \
  'https://[mycloud].ardexa.com/api/v1/tables/$WORKGROUP_ID/table_name/search' \
  --data-urlencode 'filters={"field": "event_time", "operator": ">=", "value": "2017-07-12T00:00:00Z"}' \
  --data-urlencode 'filters={"field": "source", "operator": "=", "value": "inverter-01"}'

Postman

Attached to this article is a Postman Collection (a group of saved queries) to get you started. It illustrates a number of key principles when using the API:

  • Cross Site Request Forgery (XSRF) - as a security measure, whenever you make a request to alter data (e.g. PUT, POST, DELETE), you will need to send a XSRF token in the header. The Authenticate example demonstrates this. You will need to have Postman Interceptor installed and enabled to enable cookies that carry the XSRF token you must copy into the header. If you are using the API from a programming language, most libraries support a cookie jar.

  • JSON - The Authenticate example also demonstrates how to use JSON in the body of a request

  • Authorization Header - Once you have authenticated and received your token, you will need to include this token as part of all subsequent requests. The Header is "Authorization" and the value is of the form "Bearer your.login.token"

  • Parameters - The Search example shows how to use the Params feature. The example includes a simple filter and sorts the results in descending chronological order.

Python

Here is a complete example code using Python and Requests (https://requests.readthedocs.io/en/master/)

import os
import json
import requests

TOKEN = os.environ.get("TOKEN")
CLOUD = "[mycloud]: your cloud subdomain here"
WORKGROUP_ID = "your workgroup ID here"
TABLE = "table"

headers = {
    "authorization": "Bearer {}".format(TOKEN),
}

filters = [{
    "field": "device",
    "operator": "=",
    "value": "your device ID here",
}, {
    "field": "source",
    "operator": "IN",
    "value": ["source-01", "source-02"],
}]

params = {
    "dateField": "Datetime",
    "fields": ["Datetime", "device", "source", "AC Power"],
    "rows": 10000,
    "sort": "Datetime",
    "timeframe": "2020-05-17T00:00:00 until 2020-05-17T23:59:59", 
    "timezone": "Europe/London",
    "filters": map(json.dumps, filters),
}

r = requests.get("https://{}.ardexa.com/api/v1/tables/{}/{}/search".format(CLOUD, WORKGROUP_ID, TABLE), params=params, headers=headers)
results = r.json()
print("GOT RESULTS: {}".format(len(results["records"])))
PreviousAPINextAutomated API Token Renewal

Last updated