Jenkins API with Node

This is a continuation of my previous post [Here]. 🚀

In the previous post, I went through the process of setting up Jenkins and integrating with your bit bucket account. This time around I’m going to show you how to use the Jenkins API, I will also show you how to interact with this from your Node Application. 🔥

Jenkins API

You can get to your Jenkins API by navigating to :

[JENKINS_DOMAIN]:[PORT]/api/

From here you will be able to see the available types of the API (JSON, XML, or Python). I will be using the JSON API.

You will need to create an API Token to interact with the Jenkins API, to do that you need to navigate to :

[JENKINS_DOMAIN]:[PORT]/me/configure

Further information can be found [HERE].

CURL Requests

The simplest way to talk to your Jenkins API is via the command line and using Curl.

Don’t worry too much if you have never heard of Curl, I will provide a couple of examples in Node below.

The starting syntax for all of these requests is:

[USER_NAME]:[JENKINS_TOKEN] [JENKINS_DOMAIN]:[PORT]/api/json?pretty=true

Here is a list of requests you can make using Curl

To make any of the requests below, simply replace the [KEYS] in brackets with your information and paste it into the terminal. You will be presented back with the relevant data for the given request.

Authenticate a user

curl -u [USER_NAME]:[JENKINS_TOKEN] [JENKINS_DOMAIN]:[PORT]/api/json?pretty=true

Build status

curl -g -u [USER_NAME]:[JENKINS_TOKEN] [JENKINS_DOMAIN]:[PORT]/api/json?pretty=true&tree=jobs[name,color]

Specific job config

curl -g -u [USER_NAME]:[TOKEN] [JENKINS_DOMAIN]:[PORT]/job/[JOB_NAME]/job/master/config.xml -o config.xml

Getting last build data

curl -g -u [USER_NAME]:[TOKEN] [JENKINS_DOMAIN]:[PORT]/job/[JOB_NAME]/job/master/lastBuild/api/json

Using Node 🚀

I will be using request-promise-native to call the Jenkins API.

Here are a couple of examples of accessing the Jenkins API using Node.

You can add these routes into your existing Node project, You will need to swap out the Variables with your own information:

JENKINS_BASE_URL = [JENKINS_DOMAIN]:[PORT]
JENKINS_JOB = The name given to the jenkins job you wish to get information from 
JENKINS_USER_NAME = The user name from the Jenkins credential you created earlier
JENKINS_API_KEY = The Token from the Jenkins credential you created earlier

Get Recent Builds

This will bring back information for the latest 5 builds of a specific Jenkins job.

app.get('/v1/jenkins-recent-bulids', async (req, res) => {
const { builds } = await request({
uri: `${JENKINS_BASE_URL}/job/${JENKINS_JOB}/job/master/api/json?tree=builds[number,url,result,timestamp]{0,5}`,
auth: {
user: JENKINS_USER_NAME,
pass: JENKINS_API_KEY,
},
json: true,
});
res.json({
builds,
});
});

Getting the Latest Build

This will go off and retrieve the latest build information for a specific Jenkins job.

app.get('/v1/jenkins-get-last-build', async (req, res) => {
const { result, url, timestamp } = await request({
uri: `${JENKINS_BASE_URL}/job/${JENKINS_JOB}/job/master/lastBuild/api/json`,
auth: {
user: JENKINS_USER_NAME,
pass: JENKINS_API_KEY,
},
json: true,
});
res.json({
success: result.toLowerCase() === 'success',
url,
time: moment(timestamp).format('MMM Do YYYY'),
});
});

I am limiting what I am getting from the returned data to ‘result, URL, and timestamp’ using ES6 Destructuring.

Success : Whether the job passed or failed
Url : The url to the build in Jenkins
Timestamp : the timestamp for when the job

you can get everything by changing:

const { result, url, timestamp } = await request ...

to

const data = await request ...

Summary

The Jenkins API can be really helpful if you are planning on creating some sort of admin center for a customer, allowing them visibility of how everything is going, Or even creating your own dashboard which allows you to monitor your builds without having to log into Jenkins to check. 👍