Search API

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.

Starting 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 treated as “specifically empty" instead of the former behavior of treating it like 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.

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.

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
}

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.

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.

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'

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.

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

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"

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"