Skip to main content

Search API

Introduction

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

Notable Search Functionality Differences Between Environments

Due to ongoing work for improving component search in Sonatype Nexus Repository, some functionality differences currently exist between deployments using OrientDB, H2, PostgreSQL, and/or High Availability (HA).

Specific differences and considerations are documented in Searching for Components.

Endpoints

Search Components

GET /service/rest/v1/search

This endpoint is useful for finding components based on general criteria (e.g. group, name, version) as well as format specific attributes (e.g. maven.baseVersion, npm.scope, yum.architecture). The search uses the same mechanism used by the Repository Manager UI in order to find components. Details about the criteria that can be used for searching are described in the generated documentation in Repository Manager under the administrative view System/API ( <nexus_url>/#admin/system/api).

The search takes the form of a GET request against the endpoint which returns a JSON document with information about the components (and associated assets) that were found.

As an example, we can search for all components in the maven-central repository which have 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:

Example Response

{
  "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
}

In this case we've found one component which has three assets associated with it. Each component and asset has an id that can be used with the component and asset specific endpoints. Since only one item was found, there is no need for pagination so the continuationToken has a value of null to signify that this is the last page of items. The downloadUrl can be used to directly download the asset from the repository manager.

This endpoint uses a pagination strategy that can be used to iterate through all the search results if desired.

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 which 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:

Example Response

{
  "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.

This endpoint uses apagination strategy that can be used to iterate through all the search results if desired.

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, it is necessary that the search returnsa 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'

Note that in the above example, the last parameter "maven.classsifier" has no value. This indicates that the matched asset should have no 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 which correspondingly have no value for that parameter. This technique can be used 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 sources 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'

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-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"

Empty Values

In Sonatype Nexus Repository version 3.57.0, we made enhancements to the Search APIs to improve the behavior for query parameters on fields that accept empty values.

An empty value for most fields is now treated as “specifically empty" instead of the former behavior of treating it like a wildcard.

However, note that therepositoryandformatparameters should not be empty as every component is both stored in a repository and has a format.