The DNIF Search API lets you develop an application that can retrieve and display results with the desired DQL query programmatically. With this API, you can use Restful requests to get search results for multiple streams with desired start and end time.
Prerequisites
Ensure you have the following details before using the DNIF Search API
Console IP address
Cluster ID
API Token
The API Token can be generated from the DNIF Console. To generate the token you can visit Manage Token.
API Overview
Operation
Description
Rest HTTP mapping
invoke
Returns the requested id of the search for the DQL query
POST
get status
Returns the status of task execution of requested id
GET
get result
Return the result of the search for the dql query
GET
How to use API?
Method Details
Field
Description
HTTP Method
POST
Response Format
JSON
Requires Authentication?
Yes
Query Parameters
Field
Value
Invoke
You can retrieve the task_id for a particular search by sending an HTTP POST request to its URL. You pass in the details of the search request as the query body.
cluster_id: Cluster id of the cluster you want to query data
Request Header
Field
Value
Token
Specify the token generated from DNIF Console
Content-Type
application/json
Request Body
Field
Value
Description
query_timezone (string)
Asia/Kolkata
Specify the time_zone in which you are executing the query
scope_id (string)
default
Specify the scope from where you want to retrieve data
job_type
dql
Specify the type of job you want to execute. Note: Only DQL is supported
job_execution
on-demand
Specify the supported execution type Note: Only on_demand executions are supported.
query (string)
_fetch * from event where $Stream=FIREWALL AND $StartTime=2021-09-14T17:42:00 AND $EndTime=2021-09-14T18:13:32 limit 10
Specify the DQL (DNIF Query Language) query to retrieve data
All the above parameters fields are editable and are mandatory to invoke the call
Curl Command
curl -k --location --request POST 'https://<ipaddress>/<cluster_id>/wrk/api/job/invoke' \ --header 'Token: <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "query_timezone": "Asia/Kolkata", "scope_id": "default", "job_type": "dql", "job_execution": "on-demand", "query": "_fetch * from event where $Stream=FIREWALL AND $StartTime=2021-09-14T17:42:00 AND $EndTime=2021-09-14T18:13:32 limit 10" }'
Response
Response contains all the details related to the invoked call, namely the status of the invoked call, the response results can be used to monitor progress, retrieve results, and/or delete it. Response will indicate whether the search is still being executed or it has completed or there was some error/failure.
Success
Field
Value
Description
Status_code
200
This status indicates that the call invoked was successfully completed and the search results are displayed as per the query.
This status indicates that the call invoked could not be completed due to some syntax error in the query parameter.
Status
Error
Response Value
{ "message": "query --> _fetch * from event limit | Error --> SyntaxError in _fetch query must end with limit / first / last and a valid number", "status": "error" }
Failure
Field
Value
Description
Status_code
200
This status indicates that the call invoked could not be completed due to some parameter error.
To get the status of the invoke call, you need to send an HTTP GET request to its URL. You pass the id received from the invoke call as the query parameter.
Check for the task_state result as success. When you get success as the result, execute the Get Result api to get the desired result.
Get Result
Method details
Field
Description
HTTP Method
GET
Response Format
JSON
Requires Authentication?
Yes
Parameter
Description/Value
/result
You retrieve the result for the invoke call by sending an HTTP GET request to its URL. You pass the id received from the invoke call as the query parameter.
