RESTing rather than wrestling with Jenkins

 So this is not quite Today I Learned, as I discovered this a few days back, but that doesn't work quite so well as TIL ....

Jenkins has a rather nifty REST API, where all/most of the common functions can be invoked via cURL commands.

In order to demonstrate this, I'd previously installed Jenkins onto a Virtual Server running Ubuntu, and, having created a basic Hello World Job, ran through the steps to manage the lifecycle of the job via my Mac's CLI.

Firstly, I needed to create an Access Token, using the Jenkins GUI: -

http://192.168.1.10:8080/user/hayd/configure

This generates a nice long hexadecimal string of gobbledegook, which I then use via my CLI invocations: -

Set the environment variables

export USER="hayd"

export ACCESS_TOKEN="11eec6f237adbdc9c61c15b27188d64028"

export JENKINS="http://192.168.1.10:8080"

List the available Jobs

curl --silent --request GET --user $USER:$ACCESS_TOKEN $JENKINS/api/json|jq '.jobs[].name'

of which there's one: -

"HelloWorld"

With that Job name also set as an environment variable: -

export JOB="HelloWorld"

I can then retrieve the Job's configuration: -

curl --silent --request GET --user $USER:$ACCESS_TOKEN $JENKINS/job/$JOB/config.xml --output ~/$(echo $JOB).xml

which returns an XML document: -

ls -al ~/$(echo $JOB).xml

-rw-r--r--  1 hayd  staff  694 20 Dec 14:15 /Users/hayd/HelloWorld.xml

which we can inspect: -

cat ~/$(echo $JOB).xml

<?xml version='1.1' encoding='UTF-8'?>

<project>

  <description>Say Hello</description>

  <keepDependencies>false</keepDependencies>

  <properties/>

  <scm class="hudson.scm.NullSCM"/>

  <canRoam>true</canRoam>

  <disabled>false</disabled>

  <blockBuildWhenDownstreamBuilding>false</blockBuildWhenDownstreamBuilding>

  <blockBuildWhenUpstreamBuilding>false</blockBuildWhenUpstreamBuilding>

  <triggers/>

  <concurrentBuild>false</concurrentBuild>

  <builders>

    <hudson.tasks.Shell>

      <command>#!/bin/bash

export GREETING=&quot;Hello World!&quot;

echo $GREETING</command>

      <configuredLocalRules/>

    </hudson.tasks.Shell>

  </builders>

  <publishers/>

  <buildWrappers/>

</project>

Definitely not the world's most exciting Jenkins Job ...

So let's nuke it ....

Delete the Job

curl --silent --request DELETE --user $USER:$ACCESS_TOKEN $JENKINS/job/$JOB/

This doesn't return anything .....

List the available Jobs

curl --silent --request GET --user $USER:$ACCESS_TOKEN $JENKINS/api/json|jq '.jobs[].name'

This doesn't return anything ..... because there's no longer anything to return ...

Ooops, didn't mean to delete it, where's the backup ?

Create a new job from the XML document

curl --silent --request POST --user $USER:$ACCESS_TOKEN --header 'Content-type: application/xml' $JENKINS/createItem?name=$(echo $JOB) --data @$(echo $JOB).xml

This doesn't return anything .....

List the available Jobs

curl --silent --request GET --user $USER:$ACCESS_TOKEN $JENKINS/api/json|jq '.jobs[].name'

"HelloWorld"

Phew!

TL;DR; almost all of the Jenkins GUI pages have their own REST API, as indicated by the link at the bottom of all/most pages: -

which leads to pages such as: -

http://192.168.1.10:8080/api/

which provides a useful set of suggestions e.g.

•     Controlling the amount of data you fetch
•     Create Job
•     Copy Job
•     Build Queue
•     Load Statistics
•     Restarting Jenkins

For yet more information, check out the Jenkins API documentation: -

Remote Access API 

and: -

Authenticating scripted clients