Remote access API

Hudson provides machine-consumable remote access API to its functionalities. Currently it comes in two flavors:

1. XML
2. JSON with JSONP support

Remote access API is offered in a REST-like style. That is, there is no single entry point for all features, and instead they are available under the ".../api/" URL where "..." portion is the data that it acts on.

For example, if your Hudson installation sits at http://deadlock.netbeans.org/hudson/, http://deadlock.netbeans.org/hudson/api/ will give you HTML lists all available functionalities that act on the Hudson root. For example, from here you can access all the jobs on Hudson via XML/JSON. Or if you want to access information about a particular build at http://deadlock.netbeans.org/hudson/job/trunk/lastSuccessfulBuild/, then go to http://deadlock.netbeans.org/hudson/job/trunk/lastSuccessfulBuild/api/ and you'll see the list of functionalities for the build.

The work on this front is on-going, so if you find missing features, please file an issue.

What can you do with it?

Remote API can be used to do things like these:

1. retrieve information from Hudson for programmatic consumption.
2. trigger a new build
3. create/copy jobs

Remote API and security

When your Hudson is secured, you can use HTTP BASIC authentication to authenticate remote API requests. See Authenticating scripted clients for more details.

Sample code

A simple client is available to demonstrate how you can invoke the XML from Java (Java source)

XPath selection

The XML API supports a selection by XPath by using the query parameter 'xpath'. This is convenient for extracting information in environments where XML manipulation is tedious (such as shell script.) See issue #626 for an example of how to use this.

Depth control

Sometimes the remote API doesn't give you enough information in one call. For example, if you'd like to find out all the last successful build of a given view, you'd realize that the invocation to the remote API of the view won't give you this, and you'd have to recursively call the remote API of each project to find this out. The depth control, introduced in 1.167, solves this problem. To understand this feature, it's good to start with how the remote API works.

The data model that Hudson maintains internally can be thought of as a big tree structure, and when you make a remote API call, you are getting a small subtree of it. The subtree is rooted at the object for which you made a remote API call, and the sub-tree is cut beyond certain depth to avoid returning too much data. You can adjust this cut-off behavior by specifying the depth query parameter. When you specify a positive depth value, the subtree cut-off happens that much later.

So the net result is, if you specify a bigger depth value, you'll see that the remote API will now return more data. Because of the algorithm, this works in such a way that the data returned by a bigger depth value includes all the data returned by smaller
depth value.

Detecting Hudson version

To check the version of Hudson, load the top page and check for the "X-Hudson" response header. This contains the version number of Hudson, like "1.171" This is also a good way to check if an URL is a Hudson URL.