Skip to content

Latest commit

 

History

History
1209 lines (930 loc) · 22.3 KB

REST_API.adoc

File metadata and controls

1209 lines (930 loc) · 22.3 KB

REST API for Emender-Jenkins interface

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

REST API calls

Info

/api

Gets information about the app, such as the version currently running.

Method: GET

Content-Type: application/json

Response:

{
    "name" :       "Emender Jenkins Service",
    "version" :    "0.1.0",
    "api_prefix" : "/api",
    "hostname" :   "hostname"
}

HTTP Status Code: HTTP/1.1 200 OK

Show configuration

/api/configuration

Gets information about the current configuration.

Method: GET

Content-Type: application/json

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

Banner

api/system/banners

Gets the banners that should be displayed in the UI.

Method: GET

Content­Type: application/json

Response:

[
    {
        "message": "Alpha version",
        "type":    "warning"
    }
]

HTTP Status Code: HTTP/1.1 200 OK

Create new job

/api/create_job

Creates new jenkins job and starts its build immediately (the job is added into the build queue).

Method: POST

Content­Type: 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

Delete job

/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

Get job

/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

Update job

/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

Get jobs

/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

Get job results

/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

Start job

/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

Enable job

/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

Disable job

/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

Job started

/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

Job finished

/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

Job results

/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

Jobs in queue

/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

Currently building jobs

/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

Running jobs

/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

Reload all results

/api/reload-all-results

Force to reload all results.

Method: POST

Content-Type: application/json

Post Data:

{
}

HTTP Status Code: HTTP/1.1 200 OK