• Search functionality that allows one to quickly track down artifacts and their dependency details when trying to resolve build problems.
• Browse functionality that aids in discovery of new artifacts to use in projects.

In the intervening months, Sonatype has focused its efforts on improving the usability of the Maven Central user interface in the hopes of making it the first place users look when trying to find an artifact.  Recently, users who have reaped the benefits of using the Maven Central website have asked about interacting programmatically with the search functionality.

If you pay attention to your web browser’s address bar when conducting searches on Maven Central, you can already see that a REST-style API exists.  For example, searching for “guice” from the main search box results in the following URL being generated (the following URL’s are NOT URL-encoded for the sake of readability):

• http://search.maven.org/#search|ga|1|guice

Translating the search request into English, that URL requests a basic search for any artifact (irrespective of version) containing the word “guice” in either the groupId or artifactId, returning only the first page of results.  Each row of the results shows the latest version of the artifact and the date the artifact was last updated as well as any classifiers associated with the artifact.

You can build up the complete library of search requests simply by paying attention to your web browser’s address field as you use the Maven Central website.  For the sake of convenience, we’ve collected all the URLs that make up Maven Central’s search API in a document available here.

Sadly, these URL’s are still only useful when requesting them via web browser.  They are links that can be bookmarked or e-mailed, but they do NOT work when using a non-browser agent like wget or curl.  The Maven Central user interface is essentially a browser-based application that uses Javascript to make asynchronous requests to yet another set of URL’s.  Once you make a request that looks like the URL above, the browser fires off the actual request to another Maven Central URL responsible for conducting the search and returning results that are formatted by the browser.

The sample request above, when converted to an actual Maven Central search request, looks like this:

• http://search.maven.org/solrsearch/select?q=guice&rows=20&wt=json

The actual text of your query goes in the appropriately named “q” parameter, the “rows” parameter restricts the results to a smaller number than the full result set, and the “wt” parameter can be either “xml” or “json,” depending on how your application prefers to handle results.

Some useful examples appear below.  Again, please refer to the API Guide for a complete listing:

• Fully-qualified classname search – http://search.maven.org/solrsearch/select?q=fc:”org.specs.runner.JUnit”&rows=20&wt=json
• GroupId and artifactId search that returns all available artifact versions – http://search.maven.org/solrsearch/select?q=g:”org.apache.maven.indexer”+AND+a:”maven-indexer”&rows=20&core=gav
• SHA1 search (you would need to pre-calculate the SHA1 before sending the request to Maven Central) – http://search.maven.org/solrsearch/select?q=1:”2d3c16092663da9041b171b8d3627cbafa8f0cb1″&rows=20&wt=json

In an upcoming post, I’ll describe the architecture behind Maven Central that makes all this functionality possible.

While you could do this via the Nexus UI, this wouldn’t help your automated nightly backup script. For this script to be easy to run, you’ll need to script Nexus via the REST interface. With the Nexus 1.6 release, we’ve released full documentation of the Nexus REST services available in every Nexus installation (REST doc). Continue reading for an example of how to interact with, authenticate, and manipulate a Nexus instance via the REST APIs.

The following script is written in Ruby and uses the REXML XML processor and the Net:HTTP library. Both of these libraries are available in the Ruby standard library. I tested these Ruby scripts using a standard Ruby 1.8.7 distribution. If you want to try these scripts out on your own, they will run in any standard Ruby interpreter without requiring any extra RubyGems.

Here’s the script, we’ll walk through some of the highlights after the source:

So, what’s going on in this script?

• Lines 7-15: Define some simple variables like host, port, the root URL of Nexus. We also define the status string “OUT_OF_SERVICE”. If we ran this script and then wanted to bring all hosted repositories back online, we would change this string to “IN_SERVICE”.
• Lines 17-21: Get a list of all repositories as an XML document and parse it. All Nexus REST services can return either XML or JSON, the default response if no “Content-type” header is present in the request is “application/xml”. This is a simple HTTP GET which does not require any authentication. You can find detailed documentation for the /service/local/repositories service here.
• Line 24: We’re only interested in manipulating hosted repositories. This line applies the XPath query “//repositories-item[repoType='hosted']” to the XML document and passed matching nodes to a large block that operates on each matching repository element.
• Lines 26-29: Just print out the id of each repository and the URL.
• Lines 31-34: Retrieve the status of a repository using the repository identifier. Again, this is a simple HTTP GET that does not require any authentication information. It returns an XML doc that describes the current status of the repository. Detailed documentation for the “/service/local/repositories/{repositoryId}/status” can be found here.
• LInes 36-41: Now here’s where it gets a bit fancy. The REST call to get the status was an HTTP GET, which returns an XML document. The REST call to set the status is an HTTP PUT, which accepts the same XML document. To set the repository status, we’re going to use the XML returned by a GET call to the status service and just change the “localStatus” element to either “IN_SERVICE” or “OUT_OF_SERVICE”. The statement on line 38, simply sets the value of this element in the XML document which was returned by the previous GET.
• Lines 43-50: Changing the status of a repository requires the proper privileges. For this call, we’ll need to supply the credentials set in the initial portion of the script. We will also need to make an HTTP PUT call and pass the XML document for repository status as the request body. While Nexus REST defaults to an XML response if no Content-Type is specified for simple HTTP GET calls, our HTTP PUT call to the repository status service must set the request’s “Content-Type” header to “application/xml” for status to be updated. The request body is set to the XML, which was modified on line 38, and the request is made on line 50.

That’s it. While this particular script isn’t much, it should provide a template for those of you who are interested in starting to automate common tasks via the Nexus REST API.

OPEN CHALLENGE: This this script is too verbose? Create your own Gist on GitHub.com and point to it in the comments. I’d love to see what other people could do with this sample. Expect a lot of follow-up posts to this, as we’re really interested in developing a large library of scripts for people to use.