Anyone that has used Jenkins knows that there are a lot of features and additional options besides the main functionality. Lots of them come from additional plugins but other ones are just right there ready to be used. In my last project I had to figure a way to allow users to start builds without having to access the UI. That’s how I found out about the Jenkins REST API. So I made a list of 7 Jenkins REST services I found very useful with their corresponding examples in curl. Sorry Windows users.
But before we start we have to talk about something important: Security. For these examples I will be authenticating against Jenkins using the autogenerated API token. There might be more secure ways to provide the user credentials, but it is not topic of this blog mainly because I haven’t used any of them.
1. Start a Build
This is the simplest function and it lets you execute a pipeline. In this example we are going to start a job called “mypipeline”:
curl -X POST "http://myjenkins:8080/job/mypipeline/build" -user myuser:autogeneratedtoken
2. Start a Build with parameters
This one is similar as the one above. The only difference is that in this case, the pipeline expects input parameters:
curl -X POST "http://myjenkins:8080/job/mypipeline/buildWithParameters?Parameter1=Value1&Parameter2=Value2" -user myuser:autogeneratedtoken
3. Query the last build
Here we are going to query the information regarding the last build and store it local in a file called response.out:
curl -s "http://myjenkins:8080/job/mypipeline/lastBuild/api/json" -user myuser:autogeneratedtoken > response.out
We don’t have to store the whole response and filter it out later. Since the response is a JSON object, we can filter it out directly and obtain the value we need. Here for example we obtain the build ID:
curl -s "http://myjenkins:8080/job/mypipeline/lastBuild/api/json" -user myuser:autogeneratedtoken | python -c "import sys, json; print json.load(sys.stdin)['id']"
4. Query build x
This works similar as the previous one, but this time we are not using the “lastBuild” keyword. Instead, we are going to query a specific build using the build number (112)
curl -s "http://myjenkins:8080/job/mypipeline/112/api/json" -user myuser:autogeneratedtoken > response.out
5. Download the console output
In the Jenkins UI you can view the console output after the build is complete.
You can download it also using the Rest API
curl -s "http://myjenkins:8080/job/mypipeline/lastBuild/consoleText" -user myuser:autogeneratedtoken > console.out
6. Download the build artifacts
One very powerful mechanism from Jenkins is to store artifacts. With it you can archive in Jenkins the results of one build and use them later on in another. With this method you can also download this artifacts to your local drive:
curl -s http://myjenkins:8080/job/mypipeline/lastBuild/artifact/*zip*/artifacts.zip -user myuser:autogeneratedtoken --output ./myartifacts.zip
7. Get the job data and filter it
So far we have just queried the information of a single build. There is another REST function that will allow you to query the history of all the builds. It comes in two flavours: JSON and XML.
curl --globoff -user myuser:autogeneratedtoken "http://myjenkins:8080/view/All/api/xml?tree= jobs[name,builds[number,actions[parameters[name,value]]]]&wrapper=job_names&pretty=true" > builds.out
curl --globoff -user myuser:autogeneratedtoken http://myjenkins:8080/view/All /api/json?tree=jobs[name,builds[number,actions[parameters[name,value]]]]&pretty=true
With both of these calls you will get a JSON or a XML tree structure with the respective information. In this case we are telling Jenkins to deliver the jobs, their names and all the builds that correspond to that job. For every build we will also like to have the name and value of each parameter.
In the XML version (I haven’t found a way of doing this in JSON) it is also possible to filter the result by using the xpath parameter:
curl --globoff -user myuser:autogeneratedtoken "http://myjenkins:8080/view/All/api/xml?tree= jobs[name,builds[number,actions[parameters[name,value]]]]&xpath=/*/job[starts-with(name,'Deploy')]&wrapper=job_names&pretty=true"
In the example above, only the jobs whose name starts with “Deploy” will be taken into account.
The above examples are just some of the possibilities that the Jenkin’s REST API offer. There are a lot of other functionality that can be obtained by just looking at the URL and changing the parameters. Jenkins provides also a CLI client which will let you also executes commands remotely. Nevertheless, the REST API is a very light alternative that can be used by of tools and programming languages.