Working with Jenkins Remote Access API

Jenkins exposes many details to its functionalities through remote access API and one can see metadata about job/build/view in JSON/XML format. Jenkins remote access APIs provide machine-consumable data.

Currently supports information in three flavors:

  • XML
  • JSON
  • Python

Remote access API is offered in a REST-like style which means there is no single entry point for all features. Instead they are available under the “…/api/” URL where “…” portion is the data that it acts on. This “…” portion could be an url of job, build or view.

Assume your Jenkins installation sits at http://localhost:8080/. Please check at the end of article to setup jenkins locally for testing purpose.

Visiting http://localhost:8080/api/ in browser will show just the top-level API features available, primarily a listing of the configured jobs for this Jenkins instance; Metadata is about views and its url, jobs, number of executors etc…

Url: http://localhost:8080/api/json?pretty=true

Response:

{
  "_class" : "hudson.model.Hudson",
  "assignedLabels" : [
    {
      "name" : "master"
    }
  ],
  "mode" : "NORMAL",
  "nodeDescription" : "the master Jenkins node",
  "nodeName" : "",
  "numExecutors" : 2,
  "description" : null,
  "jobs" : [
    {
      "_class" : "hudson.model.FreeStyleProject",
      "name" : "LoginFeature1",
      "url" : "http://localhost:8080/job/LoginFeature1/",
      "color" : "blue"
    },
    {
      "_class" : "hudson.model.FreeStyleProject",
      "name" : "RegressionTest",
      "url" : "http://localhost:8080/job/RegressionTest/",
      "color" : "blue"
    }
  ],
  "overallLoad" : {
    
  },
  "primaryView" : {
    "_class" : "hudson.model.AllView",
    "name" : "all",
    "url" : "http://localhost:8080/"
  },
  "quietingDown" : false,
  "slaveAgentPort" : -1,
  "unlabeledLoad" : {
    "_class" : "jenkins.model.UnlabeledLoadStatistics"
  },
  "useCrumbs" : true,
  "useSecurity" : true,
  "views" : [
    {
      "_class" : "hudson.model.ListView",
      "name" : "Feature",
      "url" : "http://localhost:8080/view/Feature/"
    },
    {
      "_class" : "hudson.model.ListView",
      "name" : "Regression",
      "url" : "http://localhost:8080/view/Regression/"
    },
    {
      "_class" : "hudson.model.AllView",
      "name" : "all",
      "url" : "http://localhost:8080/"
    }
  ]
}

If you want to access information about a particular job, e.g. http://localhost:8080/job/RegressionTest, go to http://localhost:8080/job/RegressionTest/api/ url in browser and you’ll see the list of functionalities for that job.

Url: http://localhost:8080/job/RegressionTest/api/json?pretty=true

Response:

{
  "_class" : "hudson.model.FreeStyleProject",
  "actions" : [
    {
      "_class" : "hudson.model.ParametersDefinitionProperty",
      "parameterDefinitions" : [
        {
          "_class" : "hudson.model.BooleanParameterDefinition",
          "defaultParameterValue" : {
            "_class" : "hudson.model.BooleanParameterValue",
            "value" : true
          },
          "description" : "",
          "name" : "FailBuild",
          "type" : "BooleanParameterDefinition"
        }
      ]
    },
    {
      
    },
    {
      
    },
    {
      
    },
    {
      "_class" : "com.cloudbees.plugins.credentials.ViewCredentialsAction"
    }
  ],
  "description" : "",
  "displayName" : "RegressionTest",
  "displayNameOrNull" : null,
  "fullDisplayName" : "RegressionTest",
  "fullName" : "RegressionTest",
  "name" : "RegressionTest",
  "url" : "http://localhost:8080/job/RegressionTest/",
  "buildable" : true,
  "builds" : [
    {
      "_class" : "hudson.model.FreeStyleBuild",
      "number" : 8,
      "url" : "http://localhost:8080/job/RegressionTest/8/"
    },
    {
      "_class" : "hudson.model.FreeStyleBuild",
      "number" : 7,
      "url" : "http://localhost:8080/job/RegressionTest/7/"
    },
    {
      "_class" : "hudson.model.FreeStyleBuild",
      "number" : 6,
      "url" : "http://localhost:8080/job/RegressionTest/6/"
    },
    {
      "_class" : "hudson.model.FreeStyleBuild",
      "number" : 5,
      "url" : "http://localhost:8080/job/RegressionTest/5/"
    },
    {
      "_class" : "hudson.model.FreeStyleBuild",
      "number" : 4,
      "url" : "http://localhost:8080/job/RegressionTest/4/"
    }
  ],
  "color" : "blue",
  "firstBuild" : {
    "_class" : "hudson.model.FreeStyleBuild",
    "number" : 4,
    "url" : "http://localhost:8080/job/RegressionTest/4/"
  },
  "healthReport" : [
    {
      "description" : "Build stability: 1 out of the last 5 builds failed.",
      "iconClassName" : "icon-health-60to79",
      "iconUrl" : "health-60to79.png",
      "score" : 80
    }
  ],
  "inQueue" : false,
  "keepDependencies" : false,
  "lastBuild" : {
    "_class" : "hudson.model.FreeStyleBuild",
    "number" : 8,
    "url" : "http://localhost:8080/job/RegressionTest/8/"
  },
  "lastCompletedBuild" : {
    "_class" : "hudson.model.FreeStyleBuild",
    "number" : 8,
    "url" : "http://localhost:8080/job/RegressionTest/8/"
  },
  "lastFailedBuild" : {
    "_class" : "hudson.model.FreeStyleBuild",
    "number" : 4,
    "url" : "http://localhost:8080/job/RegressionTest/4/"
  },
  "lastStableBuild" : {
    "_class" : "hudson.model.FreeStyleBuild",
    "number" : 8,
    "url" : "http://localhost:8080/job/RegressionTest/8/"
  },
  "lastSuccessfulBuild" : {
    "_class" : "hudson.model.FreeStyleBuild",
    "number" : 8,
    "url" : "http://localhost:8080/job/RegressionTest/8/"
  },
  "lastUnstableBuild" : null,
  "lastUnsuccessfulBuild" : {
    "_class" : "hudson.model.FreeStyleBuild",
    "number" : 4,
    "url" : "http://localhost:8080/job/RegressionTest/4/"
  },
  "nextBuildNumber" : 9,
  "property" : [
    {
      "_class" : "jenkins.model.BuildDiscarderProperty"
    },
    {
      "_class" : "hudson.model.ParametersDefinitionProperty",
      "parameterDefinitions" : [
        {
          "_class" : "hudson.model.BooleanParameterDefinition",
          "defaultParameterValue" : {
            "_class" : "hudson.model.BooleanParameterValue",
            "name" : "FailBuild",
            "value" : true
          },
          "description" : "",
          "name" : "FailBuild",
          "type" : "BooleanParameterDefinition"
        }
      ]
    }
  ],
  "queueItem" : null,
  "concurrentBuild" : false,
  "downstreamProjects" : [
    
  ],
  "labelExpression" : null,
  "scm" : {
    "_class" : "hudson.scm.NullSCM"
  },
  "upstreamProjects" : [
    
  ]
}

If you want to access information about a particular build, e.g. http://localhost:8080/job/RegressionTest/8, then go to http://localhost:8080/job/RegressionTest/8/api/ url in browser and you’ll see the list of functionalities for that build; Note: ‘8’ in url is build number of our interest and ‘RegressionTest’ is the job name. Change this values as per your setup.

Url: http://localhost:8080/job/RegressionTest/8/api/json?pretty=true

Response:

{
  "_class" : "hudson.model.FreeStyleBuild",
  "actions" : [
    {
      "_class" : "hudson.model.ParametersAction",
      "parameters" : [
        {
          "_class" : "hudson.model.BooleanParameterValue",
          "name" : "FailBuild",
          "value" : false
        }
      ]
    },
    {
      "_class" : "hudson.model.CauseAction",
      "causes" : [
        {
          "_class" : "hudson.model.Cause$UserIdCause",
          "shortDescription" : "Started by user admin",
          "userId" : "admin",
          "userName" : "admin"
        }
      ]
    },
    {
      
    },
    {
      
    }
  ],
  "artifacts" : [
    
  ],
  "building" : false,
  "description" : null,
  "displayName" : "#8",
  "duration" : 137,
  "estimatedDuration" : 96,
  "executor" : null,
  "fullDisplayName" : "RegressionTest #8",
  "id" : "8",
  "keepLog" : false,
  "number" : 8,
  "queueId" : 9,
  "result" : "SUCCESS",
  "timestamp" : 1546178744111,
  "url" : "http://localhost:8080/job/RegressionTest/8/",
  "builtOn" : "",
  "changeSet" : {
    "_class" : "hudson.scm.EmptyChangeLogSet",
    "items" : [
      
    ],
    "kind" : null
  },
  "culprits" : [
    
  ]
}

Please note that the work on this front is ongoing and you may not see the feature you are expecting.

Jenkins Remote Access API can do things like these:

  • retrieve information from Jenkins for programmatic consumption.
  • trigger a new build
  • create/copy jobs
  • Submitting jobs with/without parameters

Controlling the amount of data you fetch:

The tree query parameter allows you to explicitly specify and retrieve only the information you are looking for, by using an XPath-ish path expression. The value should be a list of property names to include, with sub-properties inside square braces. Try tree=jobs[name],views[name,jobs[name]] to see just a list of jobs (only giving the name) and views (giving the name and jobs they contain).

Note: for array-type properties (such as jobs in this example), the name must be given in the original plural, not in the singular as the element would appear in XML (). This will be more natural for e.g. json?tree=jobs[name] anyway: the JSON writer does not do plural-to-singular mangling because arrays are represented explicitly.

A range specifier is supported for array-type properties. For example, tree=jobs[name]{0,10} would retrieve the name of the first 10 jobs. The range specifier has the following variants:

  • {M,N}: From the M-th element (inclusive) to the N-th element (exclusive).
  • {M,}: From the M-th element (inclusive) to the end.
  • {,N}: From the first element (inclusive) to the N-th element (exclusive). The same as {0,N}.
  • {N}: Just retrieve the N-th element. The same as {N,N+1}.

Another way to retrieve more data is to use the depth=N query parameter. This retrieves all the data up to the specified depth. Compare depth=0 and depth=1 and see what the difference is for yourself. Also note that data created by a smaller depth value is always a subset of the data created by a bigger depth value.

Because of the size of the data, the depth parameter should really be only used to explore what data Jenkins can return. Once you identify the data you want to retrieve, you can then come up with the tree parameter to exactly specify the data you need.

To download and run the WAR file version of Jenkins:

To experiment all Jenkins Remote Access APIs, you might need a local Jenkins setup. Follow below steps to start Jenkins server locally for testing purpose.

The Web application ARchive (WAR) file version of Jenkins can be installed on any operating system or platform that supports Java.

  • Download the latest stable Jenkins WAR file to an appropriate directory on your machine.
  • Open up a terminal/command prompt window to the download directory.
  • Run the command java -jar jenkins.war.
  • Browse to http://localhost:8080 and wait until the Unlock Jenkins page appears.
  • Continue on with the Post-installation setup wizard below.

Start creating views and jobs as per your testing needs after completion of post installation setup.

Please let us know your thoughts in comments. Stay tuned for more posts handling Jenkins information through API.

Leave a Reply

avatar
  Subscribe  
Notify of