REST API on your datasources

You can open a REST API to any datasource using the Serenytics API tab in a datasource config page.

First, you need to create a REST API key in the admin section, in the API Keys tab.

Then, in the datasource configuration, you can authorize a given API key on this datasource.

Once a datasource is authorized, you can query it. The authentication and routes are described below.

The entry point for this api is "/data-api/".

Authentication

The authentication is done by the x-api-key header.

Here is an example in Python:

import requests

URL = "https://api.serenytics.com/data-api"
API_KEY = "XXXXXXXXX"

headers = {"x-api-key": API_KEY}

url = f"{URL}/datasources_list"
res = requests.get(url, headers=headers)
print(res.status_code)

if res.status_code == 200:
    response_json = res.json()
    print(response_json)

In cURL, that's: curl -X GET https://api.serenytics.com/data-api/datasources_list -H "x-api-key: XXXXXXXXXXX"

Security of your API KEY

Keep your API key in a safe place. Do not commit in your code. And only use https as your key is transmitted in the headers.

GET "/data-api/datasources_list"

This is a route to get the list of data-sources that you can access with your key.

POST "/data-api/query-model/"

This is a route to get the list of columns and their types in a given datasource.

Here is a python example:

URL = "https://api.serenytics.com/data-api"
headers = {"x-api-key": API_KEY}

DATASOURCE_UUID="a58d07c4-5f47-4b43-8fad-4f654f299d48"

url = f"{URL}/query-model/{DATASOURCE_UUID}"
res = requests.post(url, headers=headers)

if res.status_code == 200:
    response_json = res.json()
    print(json.dumps(response_json, indent=4))

POST "/data-api/query-data/"

This is a route to get data from the datasource. You can get all the columns. But you can also pass a query to aggregate and filter the datasource.

You can specify the output format, either as json (default) or CSV. The payload options are:

Parameters:

• format: [Optional, default: "csv"] csv or json
• csv_separator: [Optional, default: ","] the separator to use if format is csv.
• query: [Optional, default: None] a custom query (with select, groupby, orders and filters, see example below). If not defined, all columns and rows are returned.
• include_formulas: [Optional, default: False] If True, the formulas defined on the datasource will also be in the returned dataset. Only works if query is not provided.

Here is a simple example:

headers = {"x-api-key": API_KEY}
URL = "https://api.serenytics.com/data-api"

def get_data(payload):
    url = f"{URL}/query-data/{DATASOURCE_UUID}"
    res = requests.post(url, json=payload, headers=headers)

    print(res.status_code)
    if payload.get("format") == "csv":
        print(res.text)
    else:
        response_json = res.json()
        print(json.dumps(response_json, indent=4))

# example to get the data, as a CSV file, with '|' as separator
payload = {
    "format": "csv",
    "csv_separator": "|",
}
get_data(payload)

# example to get only two columns (customer_id and category), and only 5 rows
payload = {
    "query": {
        "select": [{"name": "customer_id"}, {"name": "category"}],
     },
    "limit": 5,
    "format": "csv",
    "csv_separator": "|",
}
get_data(payload)

# example with a more complex query:
# groupby category and quarter (from date column)
# with a filter (where condition) and an order_by
payload = {
    "query": {
        "select": [
            {"name": "category"},
            {"name": "date"},
            {"name": "price", "agg_function": "sum"},
            {"name": "customer_id", "agg_function": "dcount"},
            {
                "name": "$$count$$",
                "agg_function": "sum",
            },  # to count the number of rows
        ],
        "group_by": [{"name": "category"}, {"name": "date", "timeslot": "month"}],
        "where": [
            {"name": "category", "op": "!=", "value": "Bikes"},
            {
                "name": "date",
                "op": "in",
                "value": "year(-2)",
            },  # to have only current month data
        ],
        "order_by": [{"name": "category", "direction": "desc"}],  # could be asc
    },
    "format": "csv",
    "csv_separator": "|",
}