1 Core API Resources

All of the resources in this section are prefixed with /cider-ci/api. This prefix is omitted for brevity in the following.

1.1 General Properties

1.1.1 Content Types

The core API supports the content types application/json-roa+json and application/json for GET requests to all resources. The former includes hyperlinks to related resources and to this documentation.

The API evaluates the accept header including the q parameter, see Section 14 of RFC 2616 . The content type application/json-roa+json as a higher quality of service and is thus preferred. If no matching accept header is supplied the content-type application/json-roa+json will be used.

All data requests containing a body like PUT, PATCH, and POST support the content type application/json.

1.1.2 Index Resources

Several resources are conceptually indexes, e.g. /jobs/, which rather return several references to the same kind of resource, e.g. /job/:id. All of these indexes are paginated an use the page parameter with an integer value for iteration.

The content type application/json-roa+json includes a next link which should be used to iterate index resources.

1.2 Root

1.2.1 GET /

The entry-point.

1.3 Job

1.3.1 GET /jobs/:id

Returns the properties of the corresponding Job.

1.4 Job-Stats

1.4.1 GET /job/:id/stats

Returns the aggregated count of the number of tasks belonging to an Job with respect to their state.

1.5 Jobs

1.5.1 POST /jobs/create

Create a new job. Requires the body of the JSON encoded request must contain a map with the keys tree_id and key.

1.5.2 GET /jobs/

Returns a list of links each pointing to a Job. Order is descending by created_at.

1.5.2.1 Query Parameters

1.5.2.1.1 branch_head

Filters the jobs of commits which are directly referenced by the given branch with name equal to the given value.

Query string example: ?branch=master

Note: this filter is case insensitive with respect to branch-name.

1.5.2.1.2 branch_descendants

Similar as above, however it will also include all descendants of the commit referenced by the given branch name.

Examples:

1. Descendants of the branch master: ?branch_descendants=master

2. A combination of branch_head and branch_descendants can make sense: ?branch_descendants=next&branch_head=master, read: give me the jobs of the commit where the branch master points to and which are descendants of the branch next.

1.5.2.1.3 key

Filters the jobs by their key as defined in the project configuration.

1.5.2.1.4 repository_url

Filters the jobs related to commits within repositories with the url equal to the value of the parameter.

1.5.2.1.5 job_specification_id

Filters the jobs to those having referencing the given job_specification_id.

1.5.2.1.6 state

Filters the jobs with state equal to the value of the parameter.

Query string example: ?branch-name=master&repository-name=leihs&state=success

1.6 Task

1.6.1 GET /tasks/:id

Returns the properties of the corresponding Task.

1.7 Tasks

1.7.1 GET /jobs/:job_id/tasks/

Returns a list of links each pointing to a Task which belongs to Job with the id :job_id. Order is ascending with respect to the name property.

1.7.1.1 Query Parameters

1.7.1.1.1 state

Filters Tasks with state equal to the value of the parameter.

Query string example: ?page=0&state=failed

1.8 Trial

1.8.1 GET /trials/:id

Returns the properties of the trial with the id :id.

1.9 Trials

1.9.1 POST /tasks/:id/trials/retry

Create a new trial for this tasks.

1.9.2 GET /tasks/:task_id/trials/

Returns a list of links each pointing to a trial which belongs to the task with the id :task_id. Order is descending with respect to the updated_at property.

1.9.2.1 Query Parameters

1.9.2.1.1 state

Filters trials with state equal to the value of the parameter.

Query string example: ?page=0&state=failed

1.10 Tree-Attachment

1.10.1 GET /tree-attachments/:id

Returns the properties of a Tree-Attachment.

This does not return the data-stream of the attachment itself. A hyperlink to the latter is included in application/json-roa+json response types, see Content Types.

1.11 Tree-Attachments

1.11.1 GET /jobs/:job_id/attachments/

Returns a list of ids each belonging to a Tree-Attachment which belongs to the Job with the id :job_id. Note, the tree_id is a inherent property of every Job. Order is ascending with respect to the path property.

1.12 Trial-Attachment

1.12.1 GET /trial-attachments/:id

Returns the properties of a Trial-Attachment.

This does not return the data-stream of the attachment itself. A hyperlink to the latter is included in application/json-roa+json response types, see Content Types.

1.13 Trial-Attachments

1.13.1 GET /trials/:trial_id/trial-attachments/

Returns a list of ids. Each belongs to a Trial-Attachment which belongs to the trial with the id :trial_id. Order is ascending with respect to the path property.