Analytics REST API - General Info
By using the Analytics REST API, you can rely on a robust tool for Analytics UI development.
This page includes the following:
Overview
A REST API allows you to make requests for resources on a web server which, in turn, returns responses containing the requested information. Calls to REST API endpoints can be made with almost any programming language.
Unlike SOAP, REST APIs use HTTP as the transport protocol (although both server and client can be based in any language). Furthermore, a REST API does not follow a standard message format, the message specifications are only to be found in the corresponding documentation.
Do you want to get the data for a certain report? You can easily get the same data you see in the Analytics widgets via this API.
Authentication and Key Management
The API Keys
Analytics uses two types of API keys:
- A System API key
- Scoped API keys
The System API Key
-
Created during the datastore installation and used by:
- AWI for Analytics and Reporting
- Administrating the scoped API keys
System authentication is made with the pre-shared API key, which is generated during the datastore installation and also configured in the webui-plugin-analytics.
The key is located in the following directory: <Automic>\awi\config\webui-plugin-analytics\plugin.properties
It must be assigned to the authorization header in all the request to the API.
Example:
GET /analytics/api/v1/shared_dashboards/search/findByClient?client=4000 HTTP/1.1
Host: my-analytics-backend-url:8090
Authorization: f4b7e4af-3d77-4cfc-a898-2c09a9318faa
Cache-Control: no-cache
Scoped API Keys
- Created manually (system API Key required)
- Used by the Event Engine feature for injecting events (A given API key is scoped to a specific Automation Engine Client)
The following examples demonstrate the GET, POST and DELETE methods used for scoped API Keys.
GET /analytics/api/v1/apikeys
RETURNS: A list of defined scoped API keys (i.e. this does NOT list the system API keys at all).
Headers:
Authorization: <SYSTEM API KEY>
Example:
[
{
"scope": "EVENTS",
"key": "UUID",
"client": 100,
"description": "some text"
}
]
The response is described using this JSON schema:
{
"type": array,
"items": {
"type": "object",
"properties": {
"scope": {
"type": "string",
"enum": ["EVENTS"]
},
"key": {
"type": "string"
},
"client": {
"type": "integer",
"description": "This is required for EVENTS keys"
},
"description": {
"type": "string"
}
},
"required": ["scope", "key"]
}
}
POST
Creates a new API key.
POST /analytics/api/v1/apikeys
{
"scope": "EVENTS",
"client": 100,
"description": "some text"
}
Headers:
Authorization: <SYSTEM API KEY>
The POST body JSON schema:
{
"type": "object",
"properties": {
"scope": {
"type": "string",
"enum": ["EVENTS"]
},
"client": {
"type": "integer",
"description": "This is required for EVENTS keys"
},
"description": {
"type": "string"
}
},
"required": ["scope"]
}
Response JSON schema:
{
"type": "object",
"properties": {
"scope": {
"type": "string",
"enum": ["EVENTS"]
},
"key": {
"type": "string"
},
"client": {
"type": "integer",
"description": "This is required for EVENTS keys"
},
"description": {
"type": "string"
}
},
"required": ["scope", "key"]
}
Response example:
{
"key": "UUID",
"scope": "EVENTS",
"client": 100,
"description": "some text"
}
DELETE
Deletes an API key.
DELETE: /analytics/api/v1/apikeys/<UUID>
Headers:
Authorization: <SYSTEM API KEY>
Resources
You can make calls on the following resources:
- Shared dashboards - also used for the Analytics package (share action). Manage and receive information.
- Chart endpoint (only POST).
All resources can be accessed via host name + port + base url + resource (example: http://my-analytics-backend-url:8090/analytics/api/v1/shared_dashboards/).
Scenarios
The main use case for the Analytics REST API is to get data for external systems like existing Business Intelligence tools.
See also: