Request API resources
This section describes how to use REST API to get information such as the status of an asynchronous job, audit logs, and Analyzer detail view server information including, server locale, time zone, and database version.
Getting the request status
You can obtain the status of an asynchronous job. The status consists of the available request completion status and results. If the requested status does not exist, then an error message is received in a response message.
GET baseURL?action=getStatus&dataset =<Datasetname>&requestId=<reqId>
Not applicable.
Parameter | Type | Description |
action | String | getStatus
Specify the API function to be invoked. |
dataset | String | Dataset name. From 2 to 32 alphanumeric, underscore (_), and hyphen (-) characters are allowed. |
requestId | String | Asynchronous request ID. |
GET action=getStatus&dataset=defaultDs&requestId=12344 HTTP /1.1 Authorization:Basic ZnJlZDpmcmVk
{ "status":{ "total":, "matched":, "processed":, "completed":, "aborted":, "hasErrors":"" }, "result":[ { "signature":"", "name":"", "memory":{ "type":"", "name":"", "unit":"", "data":"" }, "cpu Usage":[ { "type":"", "name":"", "unit":"", "interval":, "start":"", "data":[ , , , , ] } ] } ] }
{ "status":{ "total":10, "matched":1, "processed":10, "completed":true, "aborted":false, "hasErrors":"false" }, "result":[ { "signature":"vm#cumulus1-lab-vm2", "name":"cumulus-lab-vm2", "memory":{ "type":"scalar", "name":"Memory", "unit":"", "data":"204800" }, "cpu Usage":[ { "type":"timeseries", "name":"cpu usage", "unit":"", "interval":60, "start":"20140713_230100", "data":[ 24.00, 33.00, 68.00, null, 4.00 ] } ] } ] }
Status code |
Message |
Description |
200 | OK | Request was successful, and the response body contains the requested log details. |
206 | PARTIAL CONTENT | Request is in progress, and the incremental content is available in the response body. |
400 | BAD REQUEST | Request URL or request body validation failed. Check the response body for details. |
401 | UNAUTHORIZED | Supplied authentication token is invalid or does not have the appropriate credentials to access the resource. |
404 | NOT FOUND | API server could not find a resource matching the request. |
500 | SERVER ERROR | API operation request failed. Check the response body for details. |
The following table lists the common API response codes that might be generated through the standard API. If an error response is not listed, examine the HTTP status codes to determine the best method for addressing the issue.
Response code | Message | Condition |
72020008 | Mandatory parameter {requestId} not specified. | Parameter
requestId is not specified.
|
720600E6 | Response is not present in the cache for the given requestId. | Response is not cached on the API server for the given request ID. |
720000E9 | License is not valid. | License is not uploaded, or the uploaded license is invalid or expired. |
720000E9 | Authorization needed. | Request is sent with an invalid authentication token. |
720600E6 | Response is not present in the cache for the given requestId. | Response is not cached on the API server for the given request ID. |
720600E2 | Application encountered an internal error. | API server encountered an unknown error. |
Getting an audit log
You can request audit logs based on a specific search criteria. The audit log contains the following information: date, request ID, dataset, user, user agent, HTTP method, client IP, action, request length, response code, and service time.
POST baseURL?action=getAuditLogs&dataset =<Datasetname>
{ "tw":"", "requestId":"", "user":"", "clientIp":"", "responseCode":"", "serviceTime":[ , ] }
POST action=getAuditLogs&dataset=defaultDs HTTP /1.1 Authorization: Basic ZnJlZDpmcmVk
{ "user":"admin", "responseCode":"200", "serviceTime":[ 10, 20 ] }
Parameter | Type | Description |
action | String | getAuditLogs
Specify the API function to be invoked. |
dataset | String | Dataset name. From 2 to 32 alphanumeric, underscore (_), and hyphen (-) characters are allowed. |
tw | String | (Optional) JSON list of string where the first element represents the audit start time and the second element represents end time for audit.
Date format: yyyyMMdd_HHmmss Time zone: UTC By default the last 24 hours are considered for audit. |
requestId | String | Request ID of the requested audit log.
Default: * |
user | String |
User name of the requested audit log .If you want audit logs for the specific username, then do not use the regular expression special characters in the user name. Default: * |
clientIp | String | Client IP address of the requested audit log.
Default: * |
responseCode | String | HTTP response code of the requested audit log.
Default: * |
serviceTime | Integer |
(Optional) Service time range of the requested audit log. List of service time where elements in the list represent the minimum and maximum service time. Default: 0 (Java integer maximum value) |
[ { "date":"", "requestId":"", "dataset":"", "user":"", "userAgent":"", "HTTPMethod":"", "clientIP":"", "action":"", "requestLength":"", "responseCode":, "serviceTime": } ]
[ { "date":"20150615_092909", "requestId":"363041533_8", "dataset":"defaultDs", "user":"admin", "userAgent":"Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/43.0.2357.124 Safari/537.36", "HTTPMethod":"POST", "clientIP":"192.168.1.157", "action":"createResourceDef", "requestLength":"375", "responseCode":200, "serviceTime":14 }, { "date":"20150615_100850", "requestId":"924518978_17", "dataset":"defaultDs", "user":"admin", "userAgent":"Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/43.0.2357.124 Safari/537.36", "HTTPMethod":"POST", "clientIP":"192.168.1.157", "action":"getAuditLogs", "requestLength":"12", "responseCode":200, "serviceTime":11 }, { "date":"20150615_124609", "requestId":"213068087_52", "dataset":"defaultDs", "user":"admin", "userAgent":"Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/43.0.2357.124 Safari/537.36", "HTTPMethod":"POST", "clientIP":"192.168.1.157", "action":"createResourceDef", "requestLength":"375", "responseCode":200, "serviceTime":10 } ]
Parameter |
Type |
Description |
date | String |
Time stamp of the request. Format: yyyyMMdd_HHmmss Time zone: UTC |
requestId | String | Request ID. |
dataset | String | Dataset name. |
user | String | User name that requested the request. |
userAgent | String | User agent name from which the request is received. |
HTTPMethod | String | HTTP method used for the request. |
clientIP | String | Client IP address from where this API request is received. |
action | String | Action used for this API request. |
requestLength | String | Request length. |
responseCode | Integer | HTTP response code. |
serviceTime | Integer | Total time required to execute the request. |
Status code |
Message |
Description |
200 | OK | Request was successful, and the response body contains the requested log details. |
206 | PARTIAL CONTENT | Request is in progress, and the incremental content is available in the response body. |
400 | BAD REQUEST | Request URL or request body validation failed. Check the response body for details. |
500 | SERVER ERROR | API operation request failed. Check the response body for details. |
The following table lists the common API response codes that might be generated through the standard API. If an error response is not listed, examine the HTTP status codes to determine the best method for addressing the issue.
Response code | Message | Condition |
82010002 | Invalid JSON Request. | Specified JSON input is invalid. |
8201000C | Parameter {query, startTime, endTime} not supportedParameter {query, startTime, endTime} are not supported. | Invalid parameters. |
8201000F | Invalid value specified for the parameter {tw}. | Specified value for the parameter
tw is not of a JSON list of string.
|
8201000F | Invalid value specified for the parameter {tw}. The parameter [tw] must have only two elements. | Specified JSON list for the parameter
tw does not contain 2 elements.
|
8201000F | Invalid value specified for parameter {tw}. The parameter [tw] must contain start and end time in yyyyMMdd_HHmmss format. | Specified JSON list for the parameter
tw does not contain start time or end time in valid format .
|
8201000F | Invalid value specified for parameter {tw}. The endTime must be after the startTime. | Specified
endTime is before the specified
startTime .
|
8201000F | Invalid value specified for the parameter {requestId}. | Specified value for the parameter
requestId is not of type string.
|
8201000F | Invalid value specified for the parameter {dataset}. | Specified value for the parameter dataset is not of type String. |
8201000F | Invalid value specified for the parameter {user}. | Specified value for the parameter
user is not of type string.
|
8201000F | Invalid value specified for the parameter {clientIP}. | Specified value for the parameter
clientIP is not of type string.
|
8201000F | Invalid value specified for the parameter {action}. | Specified value for the parameter
action is not of type string.
|
8201000F | Invalid value specified for the parameter {responseCode}. | Specified value for the parameter
responseCode is not of type string.
|
8201000F | Invalid value specified for the parameter {serviceTime}. | Specified value for the parameter
serviceTime is not JSON list of integer.
|
8201000F | Invalid value specified for the parameter {serviceTime}. The parameter [serviceTime] must have two element. | Specified JSON list for the parameter
serviceTime does not contain two elements.
|
8201000F | Invalid value specified for parameter {serviceTime}. The maximum serviceTime must be greater than minimum. | Specified minimum service time is greater than maximum service time. |
8201000C | Parameter {userAgent} is not supported. | Unsupported parameter specified. |
820000E2 | Application encountered an internal error. | API server encountered an unknown error. |
Stopping an API request
You can stop a running asynchronous job on the server. If the requested job does not exist, then an error message is received in a response message.
GET baseURL?action=abortRequest&dataset=<Datasetname>&requestId=<requestId of API>
Not applicable.
Parameter | Type | Description |
action | String | abortRequest
Specify the API function to be invoked. |
dataset | String | Dataset name. From 2 to 32 alphanumeric, underscore (_), and hyphen (-) characters are allowed. |
requestId | String | Asynchronous request ID. |
GET action=abortRequest&dataset=defaultDs&requestId=316829382_14 HTTP /1.1 Authorization:Basic ZnJlZDpmcmVk
If the request is stopped successfully:
{ "aborted": true, "id": "316829382_14" }
The request is processed, but not stopped:
{ "aborted": false, "id": "316829382_14" }
Cannot find the request ID in the DBresponseCache:
{ "code": "B5040016", "error": "Response is not present in cache for the given requestId '316829382_14'" }
If the request for the specified requestId is already stopped:
{ "code": "B5040018", "error": "Request for given requestId '316829382_14' is already aborted" }
Status code |
Message |
Description |
200 | OK | Request was successful, and the response body contains the requested log details. |
400 | BAD REQUEST | Request URL or request body validation failed. Check the response body for details. |
401 | UNAUTHORIZED | Supplied authentication token is invalid or does not have the appropriate credentials to access the resource. |
404 | NOT FOUND | API server could not find a resource matching the request. |
500 | SERVER ERROR | API operation request failed. Check the response body for details. |
The following table lists the common API response codes that might be generated through the standard API. If an error response is not listed, examine the HTTP status codes to determine the best method for addressing the issue.
Response code | Message | Condition |
B5020008 | Mandatory parameter {requestId} is not specified. | Parameter
requestId is not specified.
|
B50000E9 | License is not valid. | License is not uploaded, or the uploaded license is invalid or expired. |
B50000E9 | Authorization is required. | Request is sent with an invalid authentication token. |
B5040016 | Response is not present in the cache for the given request ID. | Response is not cached on the API server for the given request ID. |
B5040017 | Request for the given request ID is already completed. | Request for the given request ID is already completed. |
B5040018 | Request for the given request ID is already stopped. | Request for the given request ID is already stopped. |
B50600E2 | Application encountered an internal error | API server encountered an unknown error. |
Getting the Analyzer detail view server information
You can obtain the following server information: server locale, time zone, database version, and so on.
GET baseURL?action=getServerInfo
Not applicable.
Parameter | Type | Description |
action | String | getServerInfo
Specify API function to be invoked . |
dataset | String | Dataset name. From 2 to 32 alphanumeric, underscore (_), and hyphen (-) characters are allowed. |
includeVersion | Boolean | Specify if you want to get the version details of the database and REST API or not.
True or false Default: false |
GET action=getServerInfo&dataset=defaultDs HTTP /1.1 Authorization:Basic ZnJlZDpmcmVk
{ "uuid":"", "appVersion":"", "dbVersion":"", "apiVersion":{ "dbApiVersion":"", "alertApiVersion":"" }, "locale":"", "timeZone":"", "hostName":"", "ipAddress":"", "globalDataTimeWindow": }
{ "uuid":"8e57094d-78fa-4a25-a839-1b5e25763971", "appVersion":"HDCA Server v8.0-16070112", "dbVersion":"2.1", "apiVersion":{ "dbApiVersion":"2.0", "alertApiVersion":"1.2" }, "locale":"en-us", "timeZone":"Etc/UTC", "hostName":"cumupunws58.corp.cumulus", "ipAddress":"192.168.1.117", "globalDataTimeWindow":null }
Status code |
Message |
Description |
400 | BAD REQUEST | Request URL or request body validation failed. Check the response body for details. |
401 | UNAUTHORIZED | Supplied authentication token is invalid or does not have the appropriate credentials to access the resource. |
500 | SERVER ERROR | API operation request failed. Check the response body for details. |
The following table lists the common API response codes that might be generated through the standard API. If an error response is not listed, examine the HTTP status codes to determine the best method for addressing the issue.
Response code | Message | Condition |
C20000E4 | Mandatory parameter {dataset} not specified. | Parameter
dataset is not specified.
|
C20000E9 | License is not valid. | License is not uploaded, or the uploaded license is invalid or expired. |
C20000E9 | Authorization is required. | Request is sent with an invalid authentication token. |
C20600E2 | Application encountered an internal error. | API server encountered an unknown error. |