Taming the Jenkins JSON API with Depth and "Tree"

Jenkins has a neat JSON api - which can expose or as much or as little as you want (and even do JSON-P to boot - for direct browser shenanigans). For the api purposes, you can think of Jenkins as a tree of interesting data.

You can control the “depth” of what the api returns when you do  GET on it -  depth tells it how deep to go. (?depth=X query parameter). So if you hit up your jenkins /api/json url - you can see everything down to a certain “depth”. You can of course drill down - but if you have a lot of builds/jobs, then you can end up repeatedly loading data for each job - it is nice to get the data you want with one call of the api!

In one case I had, the difference between depth 2 and depth 3 was about 3MB of data *per request*. Ouch.

There is, however, a nicer way to control the data back - the “tree” query parameter - here you specify what elements and sub elements of a tree you want returned (nesting as needed) - this simple thing lets you craft a URL that specifies just the data you want back (at the cost of a horrendously long url that takes some time to tune) - this is also more efficient than filtering data as it was never generated and returned in the first place.

For example, https://yourjenkins/api/json?depth=2&pretty=true will return something like:


Jenkins JSON API

Don’t worry - I can’t read it either. It is a bit of a “death ray” of data - let alone if you go deeper to get the data you want. If you are loading this into a client or browser this can hurt a lot.

However, the tree query parameter to the rescue (tweak the URL):


And you see something neat like this:

Jenkins JSON API Tree


This is a lot more manageable (and in my case, exactly what I wanted and no more).

The whole point of this is to be explicit over what elements of the tree you want, and what fields.
In the above, I am saying I only want to know about “jobs”, and the “name” and “lastBuild” fields etc. Of course - you can nest these structures - so you end up with an odd looking but powerful url that tells Jenkins to only return what you care about.

The pattern is tree=keyname[field1,field2,subkeyname[subfield1]] and so on.

Hit up your Jenkins (DEV@cloud or otherwise) /api to find out more.

Hope this saves you some time.





By the way there is an xpath parameter for api/xml, which can also be used to reduce the size of responses, but unlike tree it wastes CPU time on the server. JSONP support has been dropped (by default) for security reasons.

Yes - does the tree one also work on XML api? JSON-P is such an elegant and nasty hack - but it is risky - if left open then any page could include the script and then the data is exposed to the hosting page. CORS (http://en.wikipedia.org/wiki/Cross-origin_resource_sharing) is the replacement - which in theory is just a web server config tweak (and browser support) - takes the fun out of the hack though!

Add new comment