Analysis REST API Contracts
From Yocto Project
Jump to navigationJump to search
- Work in Progress.**
This work is done when this tag is deleted.
WebHob is accessible through REST APIs, which make the backend available to any client. The data collected during the build is available on no-restrictions, anonymous, read-only API running on the local host machine.
General
The data interface is available as a search query returning a list of typed objects. The request method must be GET. The answers are always returned as JSON.
API version
The REST API is versioned as to allow further upgrades without having to maintain backward compatibility through changing the major version number. Minor version numbers are inteded to signify a capability level while maintaining compatibility.
This is the API version 1.0. All API requests are grouped under URL:
GET /api/1.0/
Object types
The API can return Build, Task, Package, Layer, Layerversion, Recipe, Variable. Each object is described below.
Search operation
The primary operation of the API is to retrieve a set of objects from the backend based on a search operation. The result will also contain all the data for the objects being returned, as to avoid separate connections to further bring the objects of the type queried.
The search operation can also specify the ordering of the results by key.
The search parameters are the same for all object types.
URI
All the search endpoints follow the same URI pattern
GET /api/1.0/{on}s/?{parameters}
- The on is the object name, one the endpoints described below.
- The parameters are described in the next section, and are the same for all search queries
Parameters
| Name | Type | Description | Comments |
|---|---|---|---|
| limit | number | The number of objects to be returned | - |
| offset | number | Offset into the search result index. | - |
| search | string | Search string for all fields | The argument is the string to searched in the database. The backend MUST return only records that match the string. |
| filter | string | String used to specify result filter function | The general form: "<FIELD>:<VALUE>[,<FIELD>:<VALUE>]*". The backend MUST only return records that have FIELD matching to the VALUE specified. The <FIELD> names for each object type are the property names of the object. |
| orderby | string | the name of the field that determens the sorting of the resuls. | "<FIELD>:<ORDER_DIRECTION>". The results are ordered by the <FIELD> values in the <ORDER_DIRECTION> order. <ORDER_DIRECTION> values may be "asc" or "desc". |
Response
All the responses are in JSON format. The response contains a set of fields describing the content of the data, and an array with the object data inside it.
Build
Returns information about the builds recorded by Webhob.
Endpoints
| Method | Endpoint | Body | Description | Comments |
|---|---|---|---|---|
| GET | /api/1.0/builds | JSON | Returns page size limited and search criteria filtered amount of builds from the data base | - |
Response
| Name | Type | Dimension | Required | Default value(s) | Description | Comments |
|---|---|---|---|---|---|---|
| [Object Root] | object | - | YES | - | - | - |
| [Object Root].count | number | - | YES | - | Total amount of builds returned in the array | - |
| [Object Root].list | object array | - | YES | - | - | To describe a generic object element of the array, the refference to it's root is "list[]" |
| [Object Root].list[].pk | number | - | YES | - | - | - |
| [Object Root].list[].model | string | - | YES | - | - | - |
| [Object Root].list[].fields | object | - | YES | - | - | - |
| [Object Root].list[].fields.outcome | number | 2 | YES | - | Signals successful or failed build | 0 - the build has failed, 1 - successful build |
| [Object Root].list[].fields.target | string | - | YES | - | The name of the build target(s) | - |
| [Object Root].list[].fields.machine | string array | - | YES | - | The selected hardware | - |
| [Object Root].list[].fields.started_on | number representation of date | - | YES | - | Marks the moment the process is started | - |
| [Object Root].list[].fields.completed_on | number representation of date | - | YES | - | Marks the moment the process is completed | - |
| [Object Root].list[].fields.errors_no | number | - | YES | - | Number of errors thrown by the build | - |
| [Object Root].list[].fields.warnings_no | number | - | YES | - | Number of warnings thrown by the build | - |
| [Object Root].list[].fields.cooker_log_path | string | - | YES | - | Path to log file | - |
| [Object Root].list[].fields.image_fstypes | string array | - | YES | - | The extensions of the root file systems produced by the build | - |
Layer
Returns information about the layers that Webhob discovered during the builds it recorded.
Endpoints
| Method | Endpoint | Body | Description | Comments |
|---|---|---|---|---|
| GET | /api/1.0/layers | JSON | Returns page size limited and search criteria filtered amount of layers from the data base | - |
Response
| Name | Type | Dimension | Required | Default value(s) | Description | Comments |
|---|---|---|---|---|---|---|
| [Object Root] | object | - | YES | - | - | - |
| [Object Root].count | number | - | YES | - | Total amount of builds to be displayed (according to filter parameter) | - |
| [Object Root].list | object array | - | YES | - | - | To describe a generic object element of the array, the refference to it's root is "list[]" |
| [Object Root].list[].pk | number | - | YES | - | - | - |
| [Object Root].list[].model | string | - | YES | - | - | - |
| [Object Root].list[].fields | object | - | YES | - | - | - |
| [Object Root].list[].fields.name | number | 2 | YES | - | The local name under which the layer is known | - |
| [Object Root].list[].fields.local_path | number | 2 | YES | - | Path to the layer on local machine | - |
| [Object Root].list[].fields.layer_index_url | number | 2 | No | - | URL to the layer index application | Possibly not available |
Layerversion
Contains information about specific version (branch:commit in GIT) of a layer used in a certain build.
Endpoints
| Method | Endpoint | Body | Description | Comments |
|---|---|---|---|---|
| GET | /api/1.0/layerversions | JSON | Returns page size limited and search criteria filtered amount of builds from the data base | - |
Response
| Name | Type | Dimension | Required | Default value(s) | Description | Comments |
|---|---|---|---|---|---|---|
| [Object Root] | object | - | YES | - | - | - |
| [Object Root].count | number | - | YES | - | Total amount of builds to be displayed (according to filter parameter) | - |
| [Object Root].list | object array | - | YES | - | - | To describe a generic object element of the array, the refference to it's root is "list[]" |
| [Object Root].list[].pk | number | - | YES | - | - | - |
| [Object Root].list[].model | string | - | YES | - | - | - |
| [Object Root].list[].fields | object | - | YES | - | - | - |
| [Object Root].list[].fields.layer_id | number | - | YES | - | pk of the layer object | - |
| [Object Root].list[].fields.branch | string | - | YES | - | the branch name of the layer | - |
| [Object Root].list[].fields.commit | string | - | YES | - | the current commit of the layer | - |
| [Object Root].list[].fields.priority | string | - | NO | - | priority of the layer, currently unavailable | - |
Task
Each build consists of a series of tasks. This is the endpoint for searching the task table.
Endpoints
| Method | Endpoint | Body | Description | Comments |
|---|---|---|---|---|
| GET | /api/1.0/tasks | JSON | Returns page size limited and search criteria filtered amount of builds from the data base | - |
Response
| Name | Type | Dimension | Required | Default value(s) | Description | Comments |
|---|---|---|---|---|---|---|
| [Object Root] | object | - | YES | - | - | - |
| [Object Root].count | number | - | YES | - | Total amount of builds to be displayed (according to filter parameter) | - |
| [Object Root].list | object array | - | YES | - | - | To describe a generic object element of the array, the refference to it's root is "list[]" |
| [Object Root].list[].pk | number | - | YES | - | - | - |
| [Object Root].list[].model | string | - | YES | - | - | - |
| [Object Root].list[].fields | object | - | YES | - | - | - |
| [Object Root].list[].fields.build_id | number | - | YES | - | Identifies the build in which the task occured | - |
| [Object Root].list[].fields.order | number | - | YES | - | The sequence ID of the task in launch order | May be NULL if never executed |
| [Object Root].list[].fields.task_executed | boolean | - | YES | - | True if task actually executed | - |
| [Object Root].list[].fields.outcome | number | - | YES | - | 0 succeeeded 1 covered by another task 2 restored from sstate 3 artifacts already existing 4 fail during execution 5 N/A (something borked) |
- |
| [Object Root].list[].fields.sstate_checksum | boolean | - | YES | - | sstate checksum of the task | - |
| [Object Root].list[].fields.path_to_sstate_obj | boolean | - | NO | - | The path to the sstate file, if it's the case | - |
| [Object Root].list[].fields.recipe_id | number | - | YES | - | Id of the recipe generating the task | - |
| [Object Root].list[].fields.task_name | string | - | YES | - | Name of the task | e.g. "do_fetch" |
| [Object Root].list[].fields.source_url | string | - | NO | - | Path to script source file | Yes, it's misnamed. |
| [Object Root].list[].fields.log_file | string | - | YES | - | Path to log file | - |
| [Object Root].list[].fields.work_directory | string | - | YES | - | cwd during task execution | - |
| [Object Root].list[].fields.script_type | number | - | NO | - | See if we executed a shell or python | 0 python 1 shell |
| [Object Root].list[].fields.line_number | number | - | NO | - | starting number of the line in the source file | - |
| [Object Root].list[].fields.py_stack_trace | string | - | NO | - | The stack trace if a python task failed | Not collected |
| [Object Root].list[].fields.disk_io | number | - | NO | - | how much disk io the task consumed; unit-less | - |
| [Object Root].list[].fields.cpu_usage | number | - | NO | - | percent of the CPU used during the task | - |
| [Object Root].list[].fields.sstate_result | number | - | NO | - | outcome of the sstate task | 0 N/A 1 missing 2 failed 3 restored succesfully |
| [Object Root].list[].message.message | string | - | NO | - | any message from the system regarding the task | - |
Recipe
Endpoints
| Method | Endpoint | Body | Description | Comments |
|---|---|---|---|---|
| GET | /api/1.0/builds | JSON | Returns page size limited and search criteria filtered amount of builds from the data base | - |
Response
| Name | Type | Dimension | Required | Default value(s) | Description | Comments |
|---|---|---|---|---|---|---|
| [Object Root] | object | - | YES | - | - | - |
| [Object Root].count | number | - | YES | - | Total amount of builds to be displayed (according to filter parameter) | - |
| [Object Root].list | object array | - | YES | - | - | To describe a generic object element of the array, the refference to it's root is "list[]" |
| [Object Root].list[].pk | number | - | YES | - | - | - |
| [Object Root].list[].model | string | - | YES | - | - | - |
| [Object Root].list[].fields | object | - | YES | - | - | - |
| [Object Root].list[].fields.outcome | number | 2 | YES | - | Signals successful or failed build | 0 - the build has failed, 1 - successful build |
| [Object Root].list[].fields.target | string | - | YES | - | The name of the build target(s) | - |
| [Object Root].list[].fields.machine | string array | - | YES | - | The selected hardware | - |
| [Object Root].list[].fields.started_on | number representation of date | - | YES | - | Marks the moment the process is started | - |
| [Object Root].list[].fields.completed_on | number representation of date | - | YES | - | Marks the moment the process is completed | - |
| [Object Root].list[].fields.errors_no | number | - | YES | - | Number of errors thrown by the build | - |
| [Object Root].list[].fields.warnings_no | number | - | YES | - | Number of warnings thrown by the build | - |
| [Object Root].list[].fields.cooker_log_path | string | - | YES | - | Path to log file | - |
| [Object Root].list[].fields.image_fstypes | string array | - | YES | - | The extensions of the root file systems produced by the build | - |
Package
Endpoints
| Method | Endpoint | Body | Description | Comments |
|---|---|---|---|---|
| GET | /api/1.0/builds | JSON | Returns page size limited and search criteria filtered amount of builds from the data base | - |
Response
| Name | Type | Dimension | Required | Default value(s) | Description | Comments |
|---|---|---|---|---|---|---|
| [Object Root] | object | - | YES | - | - | - |
| [Object Root].count | number | - | YES | - | Total amount of builds to be displayed (according to filter parameter) | - |
| [Object Root].list | object array | - | YES | - | - | To describe a generic object element of the array, the refference to it's root is "list[]" |
| [Object Root].list[].pk | number | - | YES | - | - | - |
| [Object Root].list[].model | string | - | YES | - | - | - |
| [Object Root].list[].fields | object | - | YES | - | - | - |
| [Object Root].list[].fields.outcome | number | 2 | YES | - | Signals successful or failed build | 0 - the build has failed, 1 - successful build |
| [Object Root].list[].fields.target | string | - | YES | - | The name of the build target(s) | - |
| [Object Root].list[].fields.machine | string array | - | YES | - | The selected hardware | - |
| [Object Root].list[].fields.started_on | number representation of date | - | YES | - | Marks the moment the process is started | - |
| [Object Root].list[].fields.completed_on | number representation of date | - | YES | - | Marks the moment the process is completed | - |
| [Object Root].list[].fields.errors_no | number | - | YES | - | Number of errors thrown by the build | - |
| [Object Root].list[].fields.warnings_no | number | - | YES | - | Number of warnings thrown by the build | - |
| [Object Root].list[].fields.cooker_log_path | string | - | YES | - | Path to log file | - |
| [Object Root].list[].fields.image_fstypes | string array | - | YES | - | The extensions of the root file systems produced by the build | - |
Variable
Endpoints
| Method | Endpoint | Body | Description | Comments |
|---|---|---|---|---|
| GET | /api/1.0/builds | JSON | Returns page size limited and search criteria filtered amount of builds from the data base | - |
Response
| Name | Type | Dimension | Required | Default value(s) | Description | Comments |
|---|---|---|---|---|---|---|
| [Object Root] | object | - | YES | - | - | - |
| [Object Root].count | number | - | YES | - | Total amount of builds to be displayed (according to filter parameter) | - |
| [Object Root].list | object array | - | YES | - | - | To describe a generic object element of the array, the refference to it's root is "list[]" |
| [Object Root].list[].pk | number | - | YES | - | - | - |
| [Object Root].list[].model | string | - | YES | - | - | - |
| [Object Root].list[].fields | object | - | YES | - | - | - |
| [Object Root].list[].fields.outcome | number | 2 | YES | - | Signals successful or failed build | 0 - the build has failed, 1 - successful build |
| [Object Root].list[].fields.target | string | - | YES | - | The name of the build target(s) | - |
| [Object Root].list[].fields.machine | string array | - | YES | - | The selected hardware | - |
| [Object Root].list[].fields.started_on | number representation of date | - | YES | - | Marks the moment the process is started | - |
| [Object Root].list[].fields.completed_on | number representation of date | - | YES | - | Marks the moment the process is completed | - |
| [Object Root].list[].fields.errors_no | number | - | YES | - | Number of errors thrown by the build | - |
| [Object Root].list[].fields.warnings_no | number | - | YES | - | Number of warnings thrown by the build | - |
| [Object Root].list[].fields.cooker_log_path | string | - | YES | - | Path to log file | - |
| [Object Root].list[].fields.image_fstypes | string array | - | YES | - | The extensions of the root file systems produced by the build | - |
