Skip to main content

We've Moved!

Product Documentation has moved to docs.hitachivantara.com
Hitachi Vantara Knowledge

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.

Request line
GET baseURL?action=getStatus&dataset =<Datasetname>&requestId=<reqId>
Request body

Not applicable.

Request parameters
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.
Request example
GET action=getStatus&dataset=defaultDs&requestId=12344 HTTP /1.1 Authorization:Basic ZnJlZDpmcmVk
Response body
{
  "status":{
    "total":,
    "matched":,
    "processed":,
    "completed":,
    "aborted":,
    "hasErrors":""
  },
  "result":[
    {
      "signature":"",
      "name":"",
      "memory":{
        "type":"",
        "name":"",
        "unit":"",
        "data":""
      },
      "cpu Usage":[
        {
          "type":"",
          "name":"",
          "unit":"",
          "interval":,
          "start":"",
          "data":[
            , , , , 
          ]
        }
      ]
    }
  ] 
}
Response example
{
  "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 codes

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.
NoteThis API gets the status of other API requests. It can also get all the error conditions of the original API requests.
Response codes

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.

Request line
POST baseURL?action=getAuditLogs&dataset =<Datasetname>
Request body
{
  "tw":"",
  "requestId":"",
  "user":"",
  "clientIp":"",
  "responseCode":"",
  "serviceTime":[
    , 
  ]
}
Request example
POST action=getAuditLogs&dataset=defaultDs HTTP /1.1 Authorization: Basic ZnJlZDpmcmVk
{
  "user":"admin",
  "responseCode":"200",
  "serviceTime":[
    10, 20
  ]
}
Request parameters
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)
Response body
[
  {
    "date":"",
    "requestId":"",
    "dataset":"",
    "user":"",
    "userAgent":"",
    "HTTPMethod":"",
    "clientIP":"",
    "action":"",
    "requestLength":"",
    "responseCode":,
    "serviceTime":
  }
]
Response example
[
  {
    "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
  }
]
Response parameters

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 codes

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.
Response codes

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.

Request line
GET baseURL?action=abortRequest&dataset=<Datasetname>&requestId=<requestId of API>
Request body

Not applicable.

Request parameters
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.
Request example
GET action=abortRequest&dataset=defaultDs&requestId=316829382_14 HTTP /1.1 Authorization:Basic ZnJlZDpmcmVk
Response body

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 codes

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.
Response codes

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.

Request line
GET baseURL?action=getServerInfo
Request body

Not applicable.

Request parameters
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

Request example
GET action=getServerInfo&dataset=defaultDs HTTP /1.1 Authorization:Basic ZnJlZDpmcmVk
Response body
{
  "uuid":"",
  "appVersion":"",
  "dbVersion":"",
  "apiVersion":{
    "dbApiVersion":"",
    "alertApiVersion":""
  },
  "locale":"",
  "timeZone":"",
  "hostName":"",
  "ipAddress":"",
  "globalDataTimeWindow":
}
Response example
{
  "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 codes

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.
Response codes

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.

 

  • Was this article helpful?