Search API

Available in Nexus Repository OSS and Nexus Repository Pro

Introduction

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

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:

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

{
  "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 a pagination 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 returns 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'
{
  "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 -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.

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

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