APIs

An additional tab is now available in Dashboard Configuration, which can be used to build and send custom API requests to external APIs for the purpose of generating variables in the dashboard.

Open

These variables can then be used when drilling to a URL chart. This makes it possible to drill to a page using a generated token in the URL as a means of authentication – allowing users to drill to pages that would normally require a log in step.

The creation of API requests is restricted to admins, but requests can be added to charts by users (explorer level or above) so long as the requests are assigned to a category that the user has access to. Multiple requests can be added to a chart, and these requests will be run on drill down, generating variables that are then usable in the url but are not stored or cached.

Creating an API request

Requests can be added and edited on the APIs tab in Dashboard Configuration.

Open

Request Name – enter a unique name for the API request you are creating

Category – select a category to assign the API request to. This will ensure that only users with access to that category are able to use the API request on charts

Ordering Index – selecting an ordering index will change the order that your API requests are displayed in the left panel. If requests have the same ordering index they will be ordered alphabetically by name

URL – the URL of the API you wish to access

Method - the method of the request you wish to send (selected from GET, POST, PUT and DELETE)

Body – the body of the request you wish to send to the API. This should be in valid JSON format; the field will be highlighted if invalid JSON is added

Allow unverified certificates – this option is used to ignore SSL certificates when accessing APIs. This will allow access to APIs that are served using self-signed certificates

Headers – any headers that are required for sending the request. Typically, this will include a Content-Type header for any request with a body but could also be used for sending information for authentication

Response Mapping – for mapping the values received in the APIresponse to variables in the dashboard. Variable name corresponds to the name you would like to assign to the generated variable (e.g. USER could be access in the dashboard using [[USER]]). Response key corresponds to the JSON dot notation that will provide the correct value (e.g. a JSON response of {“user”: {“first_name”:“Susan”} would use a response key of “user”.”first_name” to assign “Susan” to the variable

It is also possible to Test an API request by hitting the lightbulb button when all the relevant details are entered. This will cause JSON response to appear in the response mapping table, showing the available keys for mapping (as shown in the following screenshot)

Adding an API request to a chart

API requests can be run when drilling to a URL chart. API Requests are added to the URL chart that is being drilled to in the chart editor. This is done in the ‘API Requests’ tab in Chart Editor.

You can add a request by hitting the + button and selecting from the displayed API requests in the pop-up list

When a request has been selected, it will show the list of variables that become available when the request is run, these variables can now be used in the URL using the variable [[ ]] notation.

When drilling to the URL from the chart, the variables should be replaced and form part of the URL that is being drilled to.