Learn the Nexus REST API: Automating Sonatype Nexus

Author, Peter Lynch

Author, Peter Lynch

Like any modern web application, Nexus exposes REST based endpoints to exchange information over HTTP. If you see information in the Nexus user interface or notice a task performed using one of our Apache Maven plugins or Apache Ant tasks, then repeating the action with an automation tool that you write yourself is possible.

In Product Support we often get asked about how to quickly get up to speed learning about the REST endpoints that Nexus exposes. I’ll go over that with you in this article.

The Path of Least Resistance

Nexus has endpoints at several root paths. Assuming the default root webapp context of /nexus, these are:

  • /nexus/service/local/
    Legacy endpoints based on an old version of the Restlet Framework
  • /nexus/internal/
    Metric and monitoring endpoints provided by Dropwizard Metrics
  • /nexus/service/siesta/
    Modern endpoints based on standard JAX-RS

All requests you will need are rooted under these endpoints.

Request Espionage

The best way to learn what requests are being made is to spy on what the Nexus user interface is doing. Luckily it is not difficult with freely available tools.

For actions performed in the web browser, you can use browser developer tools to watch the HTTP requests being made. Then, simply replicate these with the programming tool of your choice.

Using Browser Developer Tools

For spying on the Nexus user interface requests in your browser, we recommend using the Google Chrome Dev Tools Network Panel or Mozilla Firefox Network Monitor.

Here’s a video that demonstrates how to use Google Chrome to spy on Nexus.

Using a Transparent Proxy

Some of you wish to replicate requests sent by our Nexus Maven Plugins or Nexus Ant Tasks. Spying on those requests is possible using a Transparent Proxy tool. Two of these we recommend are the free OWASP Zed Attack Proxy (ZAP) and the commercial Charles Proxy. Windows users may prefer Fiddler. Each of these tool websites have plenty of documentation to get you set up.

We’ll assume you have installed and are running one of the above tools at localhost:8888.

Configuring Apache Maven With a Transparent proxy

Simply edit your Maven settings.xml file to include a proxy section like the following:

<proxies>
  <proxy>
    <id>transparent-proxy</id>
    <active>true</active>
    <protocol>http</protocol>
    <host>localhost</host>
    <port>8888</port>
    <nonProxyHosts>disable-default-exclusion-of-localhost</nonProxyHosts>
  </proxy>
</proxies>

After saving this change, when you run your Maven build and it makes HTTP requests to Nexus, you should see each request in your transparent proxy. You can select the request and examine the payload included to learn the details about what requests our plugins make.

Configuring Apache Ant With a Transparent Proxy

Our Staging Ant tasks have a special configuration for configuring proxy servers. Here is an example of what your configuration may look like.

<staging:nexusStagingInfo id="target-nexus" stagingDirectory="target/ant-staging-repo">
      <staging:projectInfo groupId="com.example" artifactId="staging-test-project" version="1.0" />
      <staging:connectionInfo baseUrl="http://localhost:8081/nexus">
        <staging:authentication username="admin" password="admin123" />
        <staging:proxy host="localhost" port="8888">
        </staging:proxy>
      </staging:connectionInfo>
    </staging:nexusStagingInfo>

P.S. Detailed information about our Staging Ant Tasks are in our freely downloadable book.

Legacy Endpoint Documentation

Nexus ships with some generated REST API documentation. The documentation only applies to the legacy resources mounted under /nexus/service/local/.

Here is a video demonstrating how to find the documentation using the Plugin Console.

Nexus has used many of these endpoints since the very beginning. To allow improving our technology stack but maintain backwards compatibility, we have started to add endpoints mapped under different paths, like /nexus/service/siesta/. Unfortunately, there are no generated docs for these resources.

Source Code Sleuthing

One of the advantages Sonatype Nexus has is that a large portion of our codebase is Open Source Software. You can checkout nexus-oss from Github, open the project in an IDE and find out how the endpoints are defined, including what arguments and payloads are accepted. Be sure to use the branch or tag matching your version of Nexus.

This Is The End(point)

/nexus/service/local/* –  Classes which implement org.sonatype.plexus.rest.resource.PlexusResource are located under the org.sonatype.nexus.rest package inside the nexus-restlet1x-plugin.

/nexus/service/siesta/* – Classes which implement org.sonatype.sisu.siesta.common.Resource and use standard JAX-RS annotations to define endpoints.

/nexus/internal/* – Special Metrics related endpoints useful for devops. These are registered by the MetricsModule and are borrowed from the Dropwizard Metrics project.

Nexus 3 Will Not REST On Its Laurels

We’ve got some big improvements planned as we build out Nexus 3 to make the overall automation experience better.

The Nexus 3 user interface is driven by the efficient Sencha ExtDirect protocol instead of typical REST endpoints. This means spying on the Nexus user interface will no longer be one of the methods of learning how to automate Nexus.

Nexus 3 will eventually include a fully supported REST API that expects your automation needs to be the first-class consumer. It will be fully documented with modern developer-centric documentation. We are well into capturing and analysing your common use cases. The anonymous analytics data submitted from Nexus instances around the world are also contributing to the design.

Have you done something cool automating Nexus 2? Do you have a wish list for Nexus 3? Let us know.

Follow our progress building Nexus 3 by downloading and experimenting with the milestone releases – we always welcome your feedback at nexus-feedback@sonatype.com.

Tips From the Trenches

Manfred Moser has created a quick 7 minute video that walks through the automation of Nexus with the REST API. This is one module in our free training series. Become a member of TheNEXUS Community and watch the rest of them.

 

The following two tabs change content below.

Peter Lynch

Peter is a senior member of the Sonatype Product Support team. He has been helping to test and develop a variety of Sonatype products, with a focus on Nexus, for close to 5 years. Prior to Sonatype, Peter was a Java web application developer and software configuration specialist.

Latest posts by Peter Lynch (see all)

Authors

Related posts

4 Comments

  1. Steven Chau said:

    Thanks for your great post. It appeared just in time. I am about to automate some repository recreation (along with privileges/role/user creation) process.

    We are on Nexus Professional 2.9.1-02. If we write the automation tool using the REST api (esp. the legacy endpoints), is it going to continue to run fine when we upgrade to Nexus Professional 3.0?

    Also, I know that there’s a client library for Java. Is there one for Node.js / JavaScript? Do you know?

    Thanks!

  2. Peter Lynch said:

    Hi Steven,

    > If we write the automation tool using the REST api (esp. the legacy endpoints), is it going to continue to run fine when we upgrade to Nexus Professional 3.0?

    Our end goal for Nexus 3 will be to implement a new REST API that addresses common automation needs and is suitable for a next generation component manager. We have not finalized to what extent or if we will provide some sort of compatibility layer for the old API. We realize there are a lot of users already using the old API and will certainly take this into consideration – but we will need to balance this with the complexity involved in providing this layer. After all, Nexus 3 is and will be a radical improvement over Nexus 2 in many respects.

    > Also, I know that there’s a client library for Java. Is there one for Node.js / JavaScript? Do you know?

    Not that I’ve found specifically for Nexus, but there appear to be lots of Javascript based REST clients to work from:

    https://www.npmjs.com/search?q=rest+client

    -Peter

  3. Gösta Jonasson said:

    When will the REST services (for example the redirect endpoint or something with that functionality) be implemented in Nexus 3?

    /Eager Beaver

  4. Bjoern Ramann said:

    Hi,

    what are the minimum (read only) roles that a account needs to access the metadata with the rest interface?

    Thanks
    Bjoern

*

Top