# Search API

The Search API facilitates searching for components and assets in addition to downloading a specific asset.

Details about these endpoints are described in the generated documentation in Repository Manager under the administrative view System/API.

```
<nexus_url>/#admin/system/api
```

These endpoints use a [pagination](https://help.sonatype.com/en/pagination.html "Pagination") strategy that is used to iterate through search results.

**Changes to Search in 3.88.0**

In version 3.88.0, Sonatype Nexus Repository moved fully to SQL search and removed Elasticsearch. With this change, search behavior is more precise, and some previously supported wildcard patterns no longer work. For details, see our [SQL Search documentation](https://help.sonatype.com/en/sql-search.html "SQL Search").

## Empty Values

Empty values are treated as no value instead of a wildcard. The repository and format parameters cannot be empty as every component is stored in a repository and format. These fields are never empty.

## Search Components

```
GET /service/rest/v1/search
```

Find components based on general and format-specific attributes. The search uses the same mechanism used by the Repository Manager UI to find components.

**Note**

Search API wildcard behavior follows the SQL search rules used by component searches in the Nexus Repository UI. When `nexus.search.multi.wildcard.regex.enabled` is enabled, group, name, and version criteria support positional wildcard patterns. For details and limitations, see [SQL Search](https://help.sonatype.com/en/sql-search.html#sql-search).

The search takes the form of a GET request against the endpoint which returns a JSON document with information about the components that are found.

In this example, we search for components in the `maven-central` repository which has a group of `org.osgi`

```
curl -u admin:admin123 -X GET 'http://localhost:8081/service/rest/v1/search?repository=maven-central&group=org.osgi'
```

This returns a JSON document containing a list of items that correspond to the components found during the search:

```
{
  "items" : [ {
    "id" : "bWF2ZW4tY2VudHJhbDoyZTQ3ZGRhMGYxYjU1NWUwNzE1OWRjOWY5ZGQzZmVmNA",
    "repository": "maven-central",
    "format": "maven2",
    "group": "org.osgi",
    "name": "org.osgi.core",
    "version": "4.3.1",
    "assets": [ {
      "downloadUrl": "http://localhost:8081/repository/maven-central/org/osgi/org.osgi.core/4.3.1/org.osgi.core-4.3.1-sources.jar",
      "path": "org/osgi/org.osgi.core/4.3.1/org.osgi.core-4.3.1-sources.jar",
      "id" : "bWF2ZW4tY2VudHJhbDplMDE4OGVkMDcyOGZhNjhmNDExNzU2OGU1MjQ2NjZiYg",
      "repository": "maven-central",
      "format": "maven2",
      "checksum": {
        "sha1" : "80bfafcf783988442b3a58318face1d2132db33d",
        "md5" : "87ee0258b79dc852626b91818316b9c3"
      }
    }, {
      "downloadUrl": "http://localhost:8081/repository/maven-central/org/osgi/org.osgi.core/4.3.1/org.osgi.core-4.3.1.jar",
      "path": "org/osgi/org.osgi.core/4.3.1/org.osgi.core-4.3.1.jar",
      "id": "bWF2ZW4tY2VudHJhbDpkMDY0ODA0YThlZDVhZDZlNjhmZGU5MWNmM2NiZTgzMw",
      "repository": "maven-central",
      "format": "maven2",
      "checksum": {
        "sha1" : "5458ffe2ba049e76c29f2df2dc3ffccddf8b839e",
        "md5" : "8053bbc1b55d51f5abae005625209d08"
      }
    }, {
      "downloadUrl": "http://localhost:8081/repository/maven-central/org/osgi/org.osgi.core/4.3.1/org.osgi.core-4.3.1.pom",
      "path": "org/osgi/org.osgi.core/4.3.1/org.osgi.core-4.3.1.pom",
      "id": "bWF2ZW4tY2VudHJhbDo2NTRiYjdkMGE1OTIxMzg1OWZhMTVkMzNmYWU1ZmY3OA",
      "repository": "maven-central",
      "format": "maven2",
      "checksum": {
        "sha1" : "79391fc69dd72ad1fd983d01b4572f93f644882b",
        "md5" : "3d87a59bcdb4b131d9a63e87e0ed924a"
      }
    } ]
  } ],
  "continuationToken": null
}
```

## Search Assets

```
GET /service/rest/v1/search/assets
```

This endpoint is focused on searching for assets. All of the same search criteria are available as in the component search above, but only assets will be returned.

Let's again search the maven-central repository for assets that have a group of `org.osgi`

```
curl -u admin:admin123 -X GET 'http://localhost:8081/service/rest/v1/search/assets?repository=maven-central&group=org.osgi'
```

This returns a JSON document containing a list of items corresponding to the assets found during the search:

```
{
  "items" : [ {
    "downloadUrl": "http://localhost:8081/repository/maven-central/org/osgi/org.osgi.core/4.3.1/org.osgi.core-4.3.1-sources.jar",
    "path": "org/osgi/org.osgi.core/4.3.1/org.osgi.core-4.3.1-sources.jar",
    "id" : "bWF2ZW4tY2VudHJhbDplMDE4OGVkMDcyOGZhNjhmNDExNzU2OGU1MjQ2NjZiYg",
    "repository": "maven-central",
    "format": "maven2",
    "checksum": {
      "sha1" : "80bfafcf783988442b3a58318face1d2132db33d",
      "md5" : "87ee0258b79dc852626b91818316b9c3"
    }
  }, {
    "downloadUrl": "http://localhost:8081/repository/maven-central/org/osgi/org.osgi.core/4.3.1/org.osgi.core-4.3.1.jar",
    "path": "org/osgi/org.osgi.core/4.3.1/org.osgi.core-4.3.1.jar",
    "id": "bWF2ZW4tY2VudHJhbDpkMDY0ODA0YThlZDVhZDZlNjhmZGU5MWNmM2NiZTgzMw",
    "repository": "maven-central",
    "format": "maven2",
    "checksum": {
      "sha1" : "5458ffe2ba049e76c29f2df2dc3ffccddf8b839e",
      "md5" : "8053bbc1b55d51f5abae005625209d08"
    }
  }, {
    "downloadUrl": "http://localhost:8081/repository/maven-central/org/osgi/org.osgi.core/4.3.1/org.osgi.core-4.3.1.pom",
    "path" : "org/osgi/org.osgi.core/4.3.1/org.osgi.core-4.3.1.pom",
    "id" : "bWF2ZW4tY2VudHJhbDo2NTRiYjdkMGE1OTIxMzg1OWZhMTVkMzNmYWU1ZmY3OA",
    "repository": "maven-central",
    "format": "maven2",
    "checksum": {
      "sha1" : "79391fc69dd72ad1fd983d01b4572f93f644882b",
      "md5" : "3d87a59bcdb4b131d9a63e87e0ed924a"
    }
  } ],
  "continuationToken": null
}
```

This shows us that we found three assets and that there are no additional pages of results.

## Search and Download Asset

```
GET /service/rest/v1/search/assets/download
```

This endpoint is specifically designed to search for one asset and then redirect the request to the `downloadUrl` of that asset.

Let's say we want to download the asset corresponding to a jar whose group is `org.osgi`, name is `org.osgi.core`, and version is `4.3.1`.

To achieve this, the search must return a single asset. Continuing our example, we can use the asset search endpoint above to refine our search until it returns a single asset:

```
curl -u admin:admin123 -X GET 'http://localhost:8081/service/rest/v1/search/assets?group=org.osgi&name=org.osgi.core&version=4.3.1&maven.extension=jar&maven.classifier'
```

In the above example, the last parameter `maven.classifier` has no value. This indicates that the matched asset should have no classifier.

Using the full parameter name is not always required. For example, you may use `classifier` instead of the full `maven.classifier`.

The response returned by the above looks like this:

**Example Response**

```
{
  "items" : [ {
    "downloadUrl": "http://localhost:8081/repository/maven-central/org/osgi/org.osgi.core/4.3.1/org.osgi.core-4.3.1.jar",
    "path": "org/osgi/org.osgi.core/4.3.1/org.osgi.core-4.3.1.jar",
    "id": "bWF2ZW4tY2VudHJhbDpkMDY0ODA0YThlZDVhZDZlNjhmZGU5MWNmM2NiZTgzMw",
    "repository": "maven-central",
    "format": "maven2",
    "checksum": {
      "sha1" : "5458ffe2ba049e76c29f2df2dc3ffccddf8b839e",
      "md5" : "8053bbc1b55d51f5abae005625209d08"
    }
  } ],
  "continuationToken": null
}
```

Then we can append `/download` to produce the URL we can use to download the asset:

```
curl -L -u admin:admin123 -X GET 'http://localhost:8081/service/rest/v1/search/assets/download?group=org.osgi&name=org.osgi.core&version=4.3.1&maven.extension=jar&maven.classifier'
```

If successful, this will give us a 302 response and redirect us to the repository manager download URL for the asset. To follow a redirect with curl you will need a -L parameter.

**Example Response**

```
HTTP/1.1 302 Found
Content-Length: 0
Date: Fri, 19 Jan 2018 17:34:21 GMT
Location: http://localhost:8081/repository/maven-central/org/osgi/org.osgi.core/4.3.1/org.osgi.core-4.3.1.jar
...
```

Note that the search parameters in the example contain a parameter (`maven.classifier`) with no value:

```
...?group=org.osgi&name=org.osgi.core&version=4.3.1&maven.extension=jar&maven.classifier
```

Specifying a parameter with no value is an indicator to the search endpoint to only return assets that correspondingly have no value for that parameter. This technique can be used to filter down search results to a single asset for some formats such as Maven where the component contains multiple assets that match all search criteria specified right up to the extension. For example, a Maven component can have the actual JAR file for a library, plus have a source JAR. In these cases, just specifying `maven.extension=jar` is not specific enough to return a single asset but we can further narrow the search results by specifying that we want only the main JAR file asset, not the sources JAR by including an empty `maven.classifier` parameter.

Alternatively, let's now assume that instead of wanting the main `org.osgi.core` JAR we desire to search for and download the sources JAR (e.g. `org.osgi.core-4.3.1-sources.jar`). That is, we want to search for and download the asset corresponding to a jar whose group is `org.osgi`, name is `org.osgi.core`, version is 4.3.1 and maven.classifier is `sources`.

We can achieve this by using the asset search endpoint and including the `maven.classifier` with a specified value of `sources`:

```
curl -L -u admin:admin123 -X GET 'http://localhost:8081/service/rest/v1/search/assets/download?group=org.osgi&name=org.osgi.core&version=4.3.1&maven.classifier=sources'
```

```
HTTP/1.1 302 Found
Content-Length: 0
Date: Fri, 19 Jan 2018 17:34:21 GMT
Location: http://localhost:8081/repository/maven-central/org/osgi/org.osgi.core/4.3.1/org.osgi.core-4.3.1-sources.jar
...
```

### Downloading the Latest Version of an Asset

You can download the latest version of an asset by using the "sort=version" parameter. For example, this will download the highest semantic version available for the Maven group ID and artifact ID specified:

```
curl -L -X GET "http://localhost:8081/service/rest/v1/search/assets/download?sort=version&repository=maven-snapshots&maven.groupId=org.foo.bar&maven.artifactId=project&maven.extension=jar" -H "accept: application/json"
```

To get the latest version of a Maven snapshot, also include the base version:

```
curl -L -X GET "http://localhost:8081/service/rest/v1/search/assets/download?sort=version&repository=maven-snapshots&maven.groupId=org.foo.bar&maven.artifactId=project&maven.baseVersion=1.2.3-SNAPSHOT&maven.extension=jar" -H "accept: application/json"
```

## Search results

No results found