Emender-Jenkins Interface is controlled exclusively via REST API. Basic supported operations:
Jobs CRUD:
-
create new job (that calls Emender using its build script)
-
read job config
-
update job (reconfigure)
-
delete job
Other job-related calls:
-
start job
-
enable job
-
disable job
-
get list of all jobs
-
get job results
Other calls:
-
get info about the application
-
get banner
/api
Gets information about the app, such as the version currently running.
Method: GET
Content-Type: application/json
Example: curl http://url-to-interface:port/api
Response:
{
"name" : "Emender Jenkins Service",
"version" : "0.1.0",
"api_prefix" : "/api",
"hostname" : "hostname"
}HTTP Status Code:
HTTP/1.1 200 OK
/api/configuration
Gets information about the current configuration.
Method: GET
Content-Type: application/json
Example: curl http://url-to-interface:port/api/configuration
Response:
{
"info":
{
"version":"0.1.0"
},
"jenkins":{
"jenkins-url":"https:\/\/10.20.30.40\/",
"jenkins-job-prefix-url":"job\/",
"jenkins-job-list-url":"foobar",
"jenkins-auth":""
},
"jobs":
{
"test-jobs-suffix":"(test)"
},
"config":
{
"verbose":true,
"pretty-print":true
},
"api":
{
"prefix":"\/api"
},
"fetcher":
{
"delay":"10"
}
}HTTP Status Code:
HTTP/1.1 200 OK
api/system/banners
Gets the banners that should be displayed in the UI.
Method: GET
ContentType: application/json
Example: curl http://url-to-interface:port/api/system/banners
Response:
[
{
"message": "Alpha version",
"type": "warning"
}
]HTTP Status Code:
HTTP/1.1 200 OK
/api/create_job
Creates new jenkins job and starts its build immediately (the job is added into the build queue).
Method: POST
ContentType: application/json
Post Data (minimal version):
{
"name" : "jobName (test)",
"ssh_url_to_repo" : "git@some:repo.git",
"branch" : "preview",
"metadata": {
"uuid" : "UUID of job"
}
}Post Data (max. version):
{
"name" : "jobName (test)",
"ssh_url_to_repo" : "git@some:repo.git",
"branch" : "preview",
"additional_content_dirs" : ["dir1", "dir2"],
"metadata": {
"product" : "product name",
"version" : "product version",
"language" : "en-US",
"environment" : "preview",
"content_directory": "Book directory",
"content_type" : "book",
"uuid" : "UUID of job"
}
}Response:
{
"status" : "ok",
"jobName" : "test-Test_Product-1.0-Test_Book-en-US (test)",
"command" : "create",
"jenkinsResponse":{ "status":200 }
}HTTP Status Code:
HTTP/1.1 200 OK
Response when job already exists:
{
"status" : "error",
"jobName" : "test-Test_Product-1.0-Test_Book-en-US (test)",
"command" : "create",
"message" : "Job already exist"}
}HTTP Status Code:
HTTP/1.1 400 Bad Request
Response when the provided input is invalid:
{
"status" : "error",
"command" : "create",
"message" : "invalid input or missing input"}
}HTTP Status Code:
HTTP/1.1 400 Bad Request
{
"status" : "error",
"command" : "create",
"message" : "invalid input: branch not specified"}
}HTTP Status Code:
HTTP/1.1 400 Bad Request
{
"status" : "error",
"command" : "create",
"message" : "invalid input: git repo not specified"}
}HTTP Status Code:
HTTP/1.1 400 Bad Request
{
"status" : "error",
"command" : "create",
"message" : "invalid input: job name not specified"}
}HTTP Status Code:
HTTP/1.1 400 Bad Request
{
"status" : "error",
"command" : "create",
"job-name" : "wrong-Test_Product-1.0-Test_Book-en-US (preview)"
"message" : "The name of job is wrong"}
}HTTP Status Code:
HTTP/1.1 400 Bad Request
/api/delete_job
Deletes an existing Jenkins job.
Method: POST
Content-Type: application/json
Post Data:
{
"name": "job-name"
}Response:
{
"status" : "ok",
"jobName" : "test-Test_Product-1.0-Test_Book-en-US (test)",
"command" : "delete_job",
"jenkinsResponse":{"status":302, "other_key" : "deep and not much important data structure"}
}HTTP Status Code:
HTTP/1.1 200 OK
Response when job does not exist:
{
"status" : "error",
"jobName" : "test-Test_Product-1.0-Test_Book-en-US (test)",
"command" : "delete_job",
"message" : "Job does not exist"
}HTTP Status Code:
HTTP/1.1 404 Not Found
Response in case of invalid input:
{
"status" : "error",
"command" : "delete_job",
"message" : "job name is not specified"
}HTTP Status Code:
HTTP/1.1 400 Bad Request
{
"status" : "error",
"command" : "delete_job",
"job-name" : "wrong-Test_Product-1.0-Test_Book-en-US (preview)"
"message" : "The name of job is wrong"}
}HTTP Status Code:
HTTP/1.1 400 Bad Request
/api/get_job/{JOB_NAME}
Method: GET
Content-Type: application/json
Response:
{
"jobName": "test-Product_Name-Product_Version-Book_Name-Language (test)",
"product": "Product_Name",
"version": "Product_Version",
"uuid" : "UUID of job",
"environment": "prod",
"title": "Book_Name",
"jobStatus": "ok/unstable/failure/disabled",
"disabled" : "true/false",
"testSummary": {
"url" : "url to generated results",
"results": {"total":7,"passed":5,"failed":2}
}
}HTTP Status Code:
HTTP/1.1 200 OK
{
"jobName": "test-Product_Name-Product_Version-Book_Name-Language (test)",
"product": "Product_Name",
"version": "Product_Version",
"uuid" : "UUID of job",
"environment": "prod",
"title": "Book_Name",
"jobStatus": "failure",
"disabled" : "true/false",
"testSummary": {
"url" : "url to generated results",
"results": {"total":7,"passed":5,"failed":2}
}
}HTTP Status Code:
HTTP/1.1 200 OK
Response when test results does not exist:
{
"status" : "error",
"jobName" : "known-job",
"command" : "get_job",
"message" : "Test results does not exist"
}HTTP Status Code:
HTTP/1.1 404 Not Found
Response when job does not exist:
{
"status" : "error",
"jobName" : "unknown-job",
"command" : "get_job",
"message" : "Job does not exist"
}HTTP Status Code:
HTTP/1.1 404 Not Found
Response when the input is not valid:
{
"status" : "error",
"command" : "get_job",
"message" : "job name is not specified"
}HTTP Status Code:
HTTP/1.1 400 Bad Request
/api/update_job
Updates an existing Jenkins job.
Method: POST
Content-Type: application/json
Post Data (minimal version):
{
"name" : "test-Product_Name-Product_Version-Book_Name-Language (test)",
"ssh_url_to_repo" : "git@some:repo.git",
"branch" : "preview",
"metadata": {
"uuid" : "UUID of job",
}
}Post Data (max. version):
{
"name" : "test-Product_Name-Product_Version-Book_Name-Language (test)",
"ssh_url_to_repo" : "git@some:repo.git",
"branch" : "preview",
"additional_content_dirs" : ["dir1", "dir2"],
"metadata": {
"product": "product name",
"version": "product version",
"language": "en-US",
"environment": "preview",
"content_directory": "Book directory",
"content_type": "book"
"uuid" : "UUID of job",
}
}Response:
{
"status":"ok",
"jobName":"test-Test_Product-1.0-Test_Book-en-US (preview)",
"command":"update",
"jenkinsResponse":
{
"status":200,
"headers":
{
"Date":"Thu, 11 Aug 2016 10:08:38 GMT",
"X-Content-Type-Options":"nosniff",
"Connection":"close",
"Server":"Jetty(9.2.z-SNAPSHOT)"
},
"body":"",
"request-time":86,
"trace-redirects": ["http:\/\/10.34.3.139:8080\/job\/test-Test_Product-1.0-Test_Book-en-US%20(preview)\/config.xml"],
"orig-content-encoding":null
}
}HTTP Status Code:
HTTP/1.1 200 OK
Response when job does not exist:
{
"status" : "error",
"jobName" : "test-Test_Product-1.0-Test_Book-en-US (test)",
"command" : "update_job",
"message" : "Job does not exist"
}HTTP Status Code:
HTTP/1.1 404 Not Found
Response when input is not valid:
{
"status" : "error",
"command" : "update_job",
"message" : "invalid or missing input"
}HTTP Status Code:
HTTP/1.1 400 Bad Request
{
"status" : "error",
"command" : "update_job",
"message" : "invalid input: git repo not specified"
}HTTP Status Code:
HTTP/1.1 400 Bad Request
{
"status" : "error",
"command" : "update_job",
"message" : "invalid input: branch not specified"
}HTTP Status Code:
HTTP/1.1 400 Bad Request
{
"status" : "error",
"command" : "update_job",
"job-name" : "wrong-Test_Product-1.0-Test_Book-en-US (preview)"
"message" : "The name of job is wrong"}
}HTTP Status Code:
HTTP/1.1 400 Bad Request
/api/get_jobs /api/get_jobs?product=PRODUCT-NAME /api/get_jobs?product=PRODCUT-NAME&version=VERSION
Get list of job statuses. This list can be filtered for given product or product+version. The list should be empty when no jobs exist or if the given combination of product name and product version gives empty list.
Method: GET
Content-Type: application/json
Example: curl http://url-to-interface:port/api/system/banners
curl -X GET -v localhost:3000/api/get_jobs?product=TEST%20PRODUCT\&version=1
Response:
{"products":
{"Red Hat Enterprise Linux":
{"versions":
{"7":
{"titles":
{"Developer Guide":
{"tests":
{"preview":
{"jobName": "test-Red_Hat_Enterprise_Linux-7-Developer_Guide-en-US (preview)",
"disabled": false,
"title": "Developer Guide",
"jobStatus": "failure",
"product": "Red Hat Enterprise Linux",
"environment": "preview",
"version": "7",
"uuid" : "UUID of job",
"testSummary": {
"url" : "url to generated results",
"results":{"total":7, "passed":5, "failed":2}}},
"stage":
{"jobName": "test-Red_Hat_Enterprise_Linux-7-Developer_Guide-en-US (stage)",
"disabled":false,
"title":"Developer Guide",
"jobStatus":"failure",
"product":"Red Hat Enterprise Linux",
"environment":"stage",
"version":"7",
"uuid" : "UUID of job",
"testSummary": {
"url" : "url to generated results",
"results":{"total":7, "passed":5, "failed":2}}},
"prod":null}
}
}
},
"6":
{"titles":
{"Security Guide":
{"tests":
{"preview":
{"jobName": "test-Red_Hat_Enterprise_Linux-6-Security_Guide-en-US (preview)",
"disabled":false,
"title":"Security Guide",
"jobStatus":"unstable",
"product":"Red Hat Enterprise Linux",
"environment":"preview",
"version":"6",
"uuid" : "UUID of job",
"testSummary": {
"message":null,
"results":null},
"stage":
{"jobName": "test-Red_Hat_Enterprise_Linux-6-Security_Guide-en-US (stage)",
"disabled":false,
"title":"Security Guide",
"jobStatus":"unstable",
"product":"Red Hat Enterprise Linux",
"environment":"stage",
"version":"6",
"uuid" : "UUID of job",
"testSummary": null,
}
"prod":
{"jobName": "test-Red_Hat_Enterprise_Linux-6-Security_Guide-en-US (prod)",
"disabled":false,
"title":"Security Guide",
"jobStatus":"unstable",
"product":"Red Hat Enterprise Linux",
"environment":"prod",
"version":"6",
"uuid" : "UUID of job",
"testSummary": null,
}
}
}
}
}
}
}
}HTTP Status Code:
HTTP/1.1 200 OK
/api/get_job_results/{JOB_NAME}
Method: GET
Content-Type: application/json
Response:
{
"metadata" : {
"name":"test-book-name (test)"
},
"results" : {
"FirstTest": {
"testCase#1": [
{
"status": "info",
"message": "xxx"
}
],
"testCase#2": [
{
"status": "info",
"message": "ACLRef.xml"
},
{
"status": "info",
"message": "Administration_Guide.xml"
}
]
}
}
}HTTP Status Code:
HTTP/1.1 200 OK
Response when error occurs:
{
"status" : "error",
"jobName" : "test-Red_Hat_Certificate_System-10.0-Administration_Guide-en-US (test)",
"command" : "get_job_results",
"message" : "Job does not exist"
}HTTP Status Code:
HTTP/1.1 400 Bad Request
{
"status" : "error",
"jobName" : "test-Red_Hat_Certificate_System-10.0-Administration_Guide-en-US (test)",
"command" : "get_job_results",
"message" : "can not read test results"
}HTTP Status Code:
HTTP/1.1 400 Bad Request
/api/start_job
Starts a Jenkins job.
Method: POST
Content-Type: application/json
Post Data:
{
"name": "jobName"
}Response:
{
"status" : "ok",
"jobName" : "test-Red_Hat_Certificate_System-10.0-Administration_Guide-en-US (test)",
"command" : "start_job",
"jenkins-response":{"status":302, "other_key" : "deep and not much important data structure"}
}HTTP Status Code:
HTTP/1.1 200 OK
Response when job does not exist:
{
"status" : "error",
"jobName" : "wrong-job",
"command" : "start_job",
"message" : "Job does not exist"}
}HTTP Status Code:
HTTP/1.1 404 Not Found
Response when job name is missing in the request:
{
"status" : "error",
"command" : "start",
"message" : "job name is not specified"
}HTTP Status Code:
HTTP/1.1 400 Bad Request
/api/enable_job
Enables a Jenkins job.
Method: POST
Content-Type: application/json
Post Data:
{
"name": "jobName"
}Response:
{
"status" : "ok",
"jobName" : "test-Red_Hat_Certificate_System-10.0-Administration_Guide-en-US (test)",
"command" : "enable",
"jenkins-response":{"status":302, "other_key" : "deep and not much important data structure"}
}HTTP Status Code:
HTTP/1.1 200 OK
Response when job does not exist:
{
"status" : "error",
"jobName" : "wrong-job",
"command" : "enable_job",
"message" : "Job does not exist"
}HTTP Status Code:
HTTP/1.1 404 Not Found
Response when job name is missing in the request:
{
"status" : "error",
"command" : "enable_job",
"message" : "Job name is not specified"
}HTTP Status Code:
HTTP/1.1 400 Bad Request
/api/disable_job
Disables a Jenkins job.
Method: POST
Content-Type: application/json
Post Data:
{
"name": "jobName"
}Response:
{
"status" : "ok",
"jobName" : "test-Red_Hat_Certificate_System-10.0-Administration_Guide-en-US (test)",
"command" : "disable",
"jenkins-response":{"status":302, "other_key" : "deep and not much important data structure"}
}HTTP Status Code:
HTTP/1.1 200 OK
Response when job does not exist:
{
"status" : "error",
"jobName" : "wrong-job",
"command" : "disable_job",
"message" : "Job does not exist"
}HTTP Status Code:
HTTP/1.1 404 Not Found
Response when job name is missing in the request:
{
"status" : "error",
"command" : "disable_job",
"message" : "job name is not specified"
}HTTP Status Code:
HTTP/1.1 400 Bad Request
/api/job_started
To be called by Emender when the job is started.
Method: POST
Content-Type: application/json
Post Data:
{
"name": "jobName"
}HTTP Status Code:
HTTP/1.1 200 OK
/api/job_finished
To be called by Emender when the job is finished.
Method: POST
Content-Type: application/json
Post Data:
{
"name": "jobName"
}HTTP Status Code:
HTTP/1.1 200 OK
/api/job_results
To be called by Emender with the job data.
Method: POST
Content-Type: application/json
Post Data:
{
"metadata" : {
"name":"test-Red_Hat_Enterprise_Linux-6-Deployment_Guide (test)"
},
"results" : {
"Test1": {
"testA": [
{
"status": "pass",
"message": "The function Test1.testA() is called properly."
}
],
"testB": [
{
"status": "pass",
"message": "The function Test1.testB() is called properly."
}
],
"testCallOtherFunction": [
{
"status": "pass",
"message": "The function Test1.xyzzy() is called from another function."
}
],
"testReadLocalValue": [
{
"status": "pass",
"message": "Local variable bind to the test has the value 42"
}
],
"testReadWriteLocalValue": [
{
"status": "pass",
"message": "Old value is properly set to 42"
},
{
"status": "pass",
"message": "New value is properly set to 42"
}
]
},
"Test2": {
"testA": [
{
"status": "pass",
"message": "The function Test2.testA() is called properly."
}
],
"testB": [
{
"status": "pass",
"message": "The function Test2.testB() is called properly."
}
],
"testCallOtherFunction": [
{
"status": "pass",
"message": "The function Test2.xyzzy() is called from another function."
}
],
"testReadLocalValue": [
{
"status": "pass",
"message": "Local variable bind to the test has the value 42"
}
],
"testReadWriteLocalValue": [
{
"status": "pass",
"message": "Old value is properly set to 42"
},
{
"status": "pass",
"message": "New value is properly set to 42"
}
]
}
}
}HTTP Status Code:
HTTP/1.1 200 OK
/api/jobs_in_queue
Returns all jobs placed into Jenkins queue.
Method: GET
Content-Type: application/json
HTTP Status Code:
HTTP/1.1 200 OK
/api/currently_building_jobs
Returns all test jobs that are currently building.
Method: GET
Content-Type: application/json
HTTP Status Code:
HTTP/1.1 200 OK
/api/running_jobs
Returns all jobs placed into Jenkins queue and jobs that are currently building.
Method: GET
Content-Type: application/json
HTTP Status Code:
HTTP/1.1 200 OK