# Advanced Search REST API

APIs for automating the [Advanced Search](https://help.sonatype.com/en/sbom-search.html#advanced-search-215923 "Advanced Search") features.

## Create the Advanced Search Index

Creating or rebuilding the index is demanding on IQ Server's database. The index will continue to process after making the request so have patience.

- Requires user with the System Administrator role.
- Allow many minutes for the request to complete
- Avoid performing this operation during peak hours for large instances

```
POST /api/v2/search/advanced/index
```

Example:

```
curl -u admin:admin123 -X POST http://localhost:8070/api/v2/search/advanced/index
```

## GET Advanced Search Results

Searches are made using GET requests. Parameters need to be URL-encoded for special characters.

```
GET /api/v2/search/advanced?query=query&pageSize=10&page=1
```

The mandatory query parameter is the string to search for. Query parameters: pageSize and page are optional with default values of 10 and 1 respectively.

The allComponents parameter is used to retrieve search results including components with no violations. The default value is false and optional.

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 http://localhost:8070/api/v2/search/advanced?query=itemType%3Aorganization&pageSize=10&page=1&allComponents=true
```

In this request the ':' is URL encoded to '%3A'. As with the Advanced Search feature in the UI, asterisks '\*' are wildcards and are URL encoded to %2A.

When the search index does not exist or is unreadable, the request returns a 409 status code. Otherwise, a JSON response body is returned.

| Property | Description |
| --- | --- |
| searchQuery | 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](https://help.sonatype.com/en/sbom-search.html#advanced-search-215923 "Advanced Search"). |

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
                }
            ]
        }
    ]
}
```

## GET Export CSV Search Results

Use the following endpoint to export the results in CSV format. The endpoint receives 2 parameters:

- query parameter contains the search query
- allComponents parameter to get non-violating components (defaults to false)

```
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.

Example:

```
curl -u admin:admin123 -X GET http://localhost:8070/api/v2/search/advanced/export/csv?query=componentName%3Ajquery%2A > output.csv
```

The resulting .csv will contains violating components with a componentName field that matches the search phrase jquery\*. As we did not use the allComponents parameter, our data is limited to components associated with a violation.

### Delimiter for Advanced Search CSV Export

By default, the delimiter for advanced search CSV export is a comma, this delimiter can be changed using the [Configuration REST API](https://help.sonatype.com/en/configuration-rest-api.html "Configuration REST API").

For prior releases use the [config.yml](https://help.sonatype.com/en/config-yaml.html "Config YAML") property.

```
advancedSearchCSVExportDelimiter: ;
```

## Search results

No results found