Create a dashboard from a REST API.

Back to Tutorials
Svg background
Live connection versus using a storage
There are two very different ways to connect a REST API to Serenytics:
  • Using the Serenytics REST API connector
  • Using a storage in the Serenytics datawarehouse as a buffer for the API data
In the next two paragraphs, we'll explain how to connect your API to Serenytics using both methods. Then, we'll detail the pros/cons of each method. Please, read this last section before connecting your API.
Using the Serenytics REST API connector
In the datasource menu, create a new datasource and in the tab "Web Services & API", click on the "REST API" icon:
REST API icon
Then, enter the URL of your REST API in the configuration page of the connector:
REST API configuration example
Then, you need to fill the fields required to obtain data from your API, such as:
  • The method to use: GET or POST
  • The path to the actual data in the obtained JSON
  • The HTTP Headers
  • ...
And you also have options to transform the data obtained from your API to a table format, such as:
  • Flatten sub-objects to create new columns
  • Flatten sub-arrays to create new rows
The exhaustive documentation for these options is available here: REST API doc.
Once your API is configured, a data preview is displayed at the bottom of the config page. Then, you can build your dashboard using this datasource exactly as any other datasource.
Using a Serenytics storage
The second option to connect a REST API is to use a Python script to get the data and store it in a Serenytics storage. Thanks to the requests and serenytics Python modules, the default code is very simple:
import serenytics
import requests

STORAGE_UUID = 'UUID_OF_THE_STORAGE_USED_TO_RECEIVE_THE_API_DATA'
API_URL = 'http://api.geonames.org/countryInfoJSON?username=demo_serenytics'

r = requests.get(url=API_URL)
json_data = r.json()['geonames']

client = serenytics.Client()
ds = client.get_data_source_by_uuid(uuid=STORAGE_UUID)
ds.reload_data(new_data=json_data)
Note that we removed all the error handling code to make this example as simple as possible. Once this script is executed, the data is available in the provided Storage and you can build your dashboard against it.
Pros/Cons of each method
When using the Serenytics REST API connector:
  • Pros
    • The dashboard is "Live" (i.e. at each rendering, it queries the REST API to get the latest data).
    • Very simple to setup if the requested API is compatible with the Serenytics connector.
    • Performances are satisfying for a dashboard with only a few KPIs and small datasets.
  • Cons
    • A dashboard can be very slow if the dashboard requires many queries to the API or if it needs to get a lot of data. As filtering is done on the Serenytics side, if a filter is applied in a dashboard, the Serenytics engine will query the full dataset from the API and then apply the filter on this dataset. The same principle applies for aggregation. This can slow down a dashboard.
    • The data format returned by your API might not be compatible with our connector. In this case, you must use the second option to connect your API.
When using a Storage and a Python script:
  • Pros
    • The performance of the dashboard is a lot better as the dashboard queries its data in a Serenytics storage.
    • Whatever the format structure of the data obtained from your API, you will be able to write processing code in Python to upload it in Serenytics.
  • Cons
    • The data is updated on a regular basis (i.e. at each execution of the Python script). The dashboard is not "Live".
    • You need a few Python lines.
Note that if you can connect your API through the REST API connector but the dashboard is too slow, you can also:
  • Configure the cache on the API datasource.
  • Create an ETL step to store the data from this connector in a storage and query this storage in your dashboard. This will be exactly as the Python script above (simpler, but less customizable).
Conclusion
To summarize, we advise you to use the Serenytics connector in a dashboard only if you need to display 'live' data. Otherwise, we advise you to store the data in a Serenytics storage (either using an ETL step or using a Python script as described here).
×