Software Engineering

7 useful Jenkins Rest services

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.

API Token

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”:

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:

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:

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:

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)

5. Download the console output

In the Jenkins UI you can view the console output after the build is complete.

Jenkins Console Output

You can download it also using the Rest API

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:

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.

XML

JSON

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:

In the example above, only the jobs whose name starts with “Deploy” will be taken into account.

Conclusion

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.

References