This post runs through a simple Ruby script that manipulates the offline/online status of hosted Nexus repositories. Such a script would be useful if you need to manipulate the storage of a repository while Nexus is running. Assume you have a script that needs to backup the storage directory of all of your hosted directories once a night. If you wanted to make sure that your repository isn't altered in the middle of a backup, you would put each hosted repository out of service before the backup job ran. After the job completed, you would put all of your hosted servers back into service.
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.
