A presentation about Jenkins API. Why you should use it, how to use it and what libraries already take advantage of it.

1. Jenkins API
Arie Bregman
InfuseCon@2018

2. Agenda
● Jenkins API
○ Overview
○ How to use
○ Examples
○ The ugly side
● Pykins
○ Overview
○ Examples

3. Jenkins API overview● REST API
● Several data formats
○ XML
○ JSON
○ Python
● Retrieve Data
○ Jobs, Builds, Plugins, Nodes
● Actions
○ Trigger Jobs, Update Plugins
Python?

4. Why using Jenkis API?
● Dashboard
● Scripts
● Pull the specific data you need
● Jenkins UI is bad for your health

5. Using Jenkins API
● Add ‘/api’ to Jenkins URL
○ https://my_jenkins/api
○ General permanent description + relevant documentation to the endpoint of your
URL

6. ● https://my_jenkins/job/my_job/api
● Add /api/json or /api/xml to get the actual data
○ Same data, different formats
○ There is a link at the the bottom of each page
in Jenkins UI
● Next, examples! :)

7. Example #1 - Baby Steps
https://<jenkins_server>/api/json
● Master server
● Jobs
● Views
{"_class":"hudson.model.Hudson","assignedLab
els":[{}],"mode":"NORMAL","nodeDescription":"t
he master Jenkins
node","nodeName":"","numExecutors":2,"descri
ption":null,"jobs":[{"_class":"org.jenkinsci.plu
gins.workflow.job.WorkflowJob","name":"ov
b-poc","url":"http://X/job/ovb-
poc/","color":"red"},{"_class":"org.jenkinsci.
plugins.workflow.job.WorkflowJob","name":
"bla-poc","url":"http://X/job/bla-
poc/","color":"blue"},...

8. Example #2 - Depth
https://<jenkins_server>/api/json?depth=1
● Depth = 1 -> Description, Builds, Health report
● Depth = 2 -> SCM changes, artificats
● ...
● Depth = 10

9. Example #3 - Tree
https://<jenkins_server>/api/json?tree=jobs[name]
● tree=key[field1, field2, field3, subkey[subfield1, subfield2]]
● Elements and sub-elements of a tree you want to get
● Nested as required
{"_class":"org.jenkinsci.plugins.workflow.job.WorkflowJob","name":"my_job"},{"_clas
s":"org.jenkinsci.plugins.workflow.job.WorkflowJob","name":"Z-
job"},{"_class":"org.jenkinsci.plugins.workflow.job.WorkflowJob","name":"Y-
job"},{"_class":"org.jenkinsci.plugins.workflow.job.WorkflowJob","name":"X-job"}, ...

10. Example #4 - Tree with subkeys
https://<my_j>/api/json?tree=jobs[name,lastBuild[result,changeSet[items[author]]]]
{"_class":"hudson.model.FreeStyleProject","name":"export-results-to-polarion-
poc""lastBuild":{"_class":"hudson.model.FreeStyleBuild",,"result":"FAILURE","chang
eSet":{"_class":"hudson.plugins.git.GitChangeSetList","items":[]}}}

11. The ugly side of Jenkins API
● http://my_jenkins/api/json?kowabunga will work just fine
● https://<jenkins_server>/api/json?depth=20 is the easiest way to kill a
Jenkins server
● Documentation

12. Python Libraries
● python-jenkins
○ OpenStack project
● Jenkinsapi
○ Maintained by pycontribs
○ More active at this point of time

13. Pykins
● Both Python API and CLI for Jenkins in one package!
● Custom calls support
● Additional functionality to Jenkins
● Maintained by couple of companies

14. Example #1 - get jobs
>>> j = pykins.Jenkins(“http://my_jenkins”)
>>> j.get_jobs()
{ jobs: [‘job1’, ‘job2’, ‘jobs3’] }
~ pykins jobs list
{ jobs: [‘job1’, ‘job2’, ‘jobs3’ }
Python
API
CL
I

15. Example #2 - get plugins
>>> j.get_plugins(version=True,
installed=True)
{ plugins: [
{‘name’: ‘LDAP’, ‘version’: 0.0.1, installed=True},
{‘name’: ‘Git’, ‘version’: 2.3.7, installed=True},
… ] }
~ pykins plugin list --format flat
LDAP
Git
Python
API
CL
I

16. Example #3 - Active Jobs
>>> j.get_non_active_jobs(days=200)
{ jobs: [‘job5, ‘job16’] }
~ pykins job list non-active --days 20 --simple
job51
job62
Python
API
CL
I