Advanced Search REST API - v2
The Advanced Search API allows you to:
POST to Create a Search Index
Creating a search index is a resource intensive operation that can be demanding on IQ Server's database and which can take in the order of minutes to complete depending on IQ Server's database size.
We highly recommend only performing this operation at times when your IQ Server is under minimal usage.
To create a search index, a System Administrator can issue a POST request to the following path:
POST /api/v2/search/advanced/index
For example, using a local installation of IQ Server with its default configuration, a request using the cURL tool would be:
curl -u admin:admin123 -X POST http://localhost:8070/api/v2/search/advanced/index
This is an asynchronous operation, which means that when the REST request completes the index will likely still be under construction.
GET Search Results
To search, an IQ Server user can issue a GET request to the following path:
GET /api/v2/search/advanced?query=query&pageSize=10&page=1
In the above call,
query
is the string you wish to search for. It is the only mandatory query parameter. Query parameters
pageSize
and
page
are optional with default values of 10 and 1 respectively.
allComponents is a new query parameter that, if set to true, retrieves search results including components with no vulnerabilities. This parameter is optional and has default value of false.
For example, using a local installation of IQ Server with its default configuration, a request using the cURL tool would be:
curl -u admin:admin123 -X GET http://localhost:8070/api/v2/search/advanced?query=itemType%3Aorganization&pageSize=10&page=1&allComponents=true
Take care to URL encode any special characters that require it, for example, in the above request ':' is URL encoded to '%3A'. As with the Advanced Search feature in the UI, asterisks '*' are wildcards and are URL encoded to %2A.
If a search index does not exist or is unreadable, then the request yields a HTTP conflict status code of 409, otherwise a JSON response body is returned with the following properties:
| Property | Description |
|---|---|
query | The requested search query. |
page | The requested page number of the results. |
pageSize | The requested number of results per page. |
totalNumberOfHits | The total number of results. |
isExactTotalNumberOfHits | If the total number of results is exact, then this is true. Otherwise it's false indicating that this is a lower bound on the total number of results. An inexact value can happen when there is a large number of results making an exact count too expensive to compute. |
groupingByDTOS | An array where each element is a collection of search results that have been grouped according to some criteria. |
groupIdentifier | The field name that the search results have been grouped on. |
groupBy | The field value that the search results have been grouped on. |
additionalInfo | This holds information shared between each element in a group e.g. when grouping on a security vulnerability, this is its description. |
searchResultItemDTOS | An array of search results, each of these will contain an itemType indicating what type of result it is as well as a resultIndex indicating the order of the result. A lower resultIndex indicates a more relevant result that will appear earlier. Additionally each element may contain properties representing field names and values relevant to its type. |
An example of a successful response body for the above example search request is as follows:
{
"searchQuery": "itemType:organization",
"page": 1,
"pageSize": 10,
"totalNumberOfHits": 2,
"isExactTotalNumberOfHits": true,
"groupingByDTOS": [
{
"groupIdentifier": "ITEM_TYPE",
"groupBy": "ORGANIZATION",
"additionalInfo": null,
"searchResultItemDTOS": [
{
"itemType": "ORGANIZATION",
"organizationId": "ROOT_ORGANIZATION_ID",
"organizationName": "Root Organization",
"resultIndex": 1
},
{
"itemType": "ORGANIZATION",
"organizationId": "aadb7e6a9c1444378498af5e0f7decab",
"organizationName": "org",
"resultIndex": 2
}
]
}
]
}Before release 100, when Advanced Search was an experimental feature the aforementioned endpoints would be different:
POST /api/experimental/search/advanced/index
GET /api/experimental/search/advanced?search=query&pageSize=10&page=1
GET Export CSV Search Results
A new endpoint was added in order to export the advanced search results in the CSV format. The endpoint receives 2 parameters, query parameter contains the search query to export and allComponents parameter is optional to get also non-vulnerable components in the export results with false as the default value.
GET /api/v2/search/advanced/export/csv?query=query&allComponents=true
Fields are filled according to the item type, and an empty field means that the item type does not contain the value itself.
For example, using a local installation of IQ Server with its default configuration on a Windows machine, a request using the cURL tool would be:
curl -u admin:admin123 -X GET http://localhost:8070/api/v2/search/advanced/export/csv?query=componentName%3Ajquery%2A > output.csv
This outputs a .csv file at the terminal's current directory for all items with a componentName field that matches the search phrase jquery*. Because we did not use the allComponents parameter, our data is limited to components associated with a vulnerability.
Delimiter for Advanced Search CSV Export
By default, the delimiter for advanced search CSV export is a comma, this delimiter can be changed.
For IQ Server Release 142 and later
NEW IN RELEASE 142
Via the configuration REST API.
For IQ Server Release 141 and prior
In the server configuration file e.g. for a semicolon :
advancedSearchCSVExportDelimiter: ;