Analysis REST API Contracts

From Yocto Project
Jump to navigationJump to search


  • _Implementation available on contrib/webhob-poky/master-next_

This page gives you information on the Toaster API and its search operation URI, parameters, and responses. You might also be interested in the Toaster installation and running instructions.

Toaster 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 intended 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, Recipe Dependencies, Package Dependencies, Configuration Variables and Log Messages. 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 Toaster.

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.build_name string - YES - Build name Known issues: 5187
[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 Known issues: 5186
[Object Root].list[].fields.completed_on number representation of date - YES - Marks the moment the process is completed Known issues: 5186
[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 Known issues: 5187
[Object Root].list[].fields.distro string - YES - Distro name -
[Object Root].list[].fields.distro_version string - YES - Distro version -
[Object Root].list[].fields.bitbake_version string - YES - BitBake version -

Target

Returns information about the builds recorded by Webhob.

Endpoints

Method Endpoint Body Description Comments
GET /api/1.0/targets JSON Returns page size limited and search criteria filtered amount of targets 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.build number - YES - The ID of the build that created this target -
[Object Root].list[].fields.target string - YES - The name of the build target -
[Object Root].list[].fields.image_fstypes string - YES - The file types of the build target Space-separated file name suffixes. Known issues: 5188
[Object Root].list[].fields.file_name string - YES - The file name of the build target Known issues: 5189
[Object Root].list[].fields.file_size number - YES - The file size of the build target Known issues: 5228
[Object Root].list[].fields.is_image boolean - YES False True if one of the build targets is an image recipe -

Target Installed Packages

  • Information collected only if buildhistory is enabled

Endpoints

Method Endpoint Body Description Comments
GET /api/1.0/target_packages 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.target number - YES - The pk of the target that has this package -
[Object Root].list[].fields.recipe number - YES - The pk of the recipe that generated this package Known issues: 5276
[Object Root].list[].fields.name string - YES - Package name -
[Object Root].list[].fields.version string - YES - Package version Known issues: 5276
[Object Root].list[].fields.size number - YES - The size of the package, in bytes -

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 string - YES - The local name under which the layer is known -
[Object Root].list[].fields.local_path string - YES - Path to the layer on local machine -
[Object Root].list[].fields.layer_index_url URL - NO - URL to the layer index application Possibly not available. Known issues: 5192

Layer version

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 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 number - NO - Priority of the layer -

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 number - YES - Identifies the build in which the task occurred -
[Object Root].list[].fields.order number - YES - The sequence ID of the task in launch order
[Object Root].list[].fields.task_executed boolean - YES - True if task actually executed -
[Object Root].list[].fields.outcome number 6 YES 5 0 Executed successfully
1 Covered by another task
2 Restored from sstate
3 Artifacts already existing
4 Fail during execution
5 Not available
Known issues: 5216
[Object Root].list[].fields.sstate_checksum string - YES - Sstate checksum of the task -
[Object Root].list[].fields.path_to_sstate_obj string - NO - The path to the sstate file, if applicable Known issues: 5252
[Object Root].list[].fields.recipe 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) Known issues: 5255
[Object Root].list[].fields.log_file string - YES - Path to log file Will always be empty. Data comes into logfile (see 5267)
[Object Root].list[].fields.logfile string - YES - Path to log file Known issues: 5267
[Object Root].list[].fields.work_directory string - YES - Cwd during task execution Known issues: 5253
[Object Root].list[].fields.script_type number 2 NO 0 See if we executed a shell or python 0 python
1 shell
Known issues: 5075
[Object Root].list[].fields.line_number number - NO - Starting number of the line in the source file Known issues: 5254
[Object Root].list[].fields.py_stack_trace string - NO - The stack trace if a python task failed Will always be empty. Data collected in the 'message' field of LogMessage (see 5251)
[Object Root].list[].fields.disk_io number - NO - Time spent by the task in I/O operations (in ms) Known issues: 5073
[Object Root].list[].fields.cpu_usage number - NO - Percent of the CPU used during the task Known issues: 5073
[Object Root].list[].fields.sstate_result number 4 NO 0 Outcome of the sstate task 0 N/A
1 Missing
2 Failed
3 Restored successfully
Known issues: 5220
[Object Root].list[].message.message string - NO - Any message from the system regarding the task -
[Object Root].list[].message.elapsed_time string - NO - Time taken by the task to complete (in seconds) -

Task Dependencies

Returns the package dependency data

Endpoints

Method Endpoint Body Description Comments
GET /api/1.0/task_dependencies 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.task number - YES - The pk of the target task -
[Object Root].list[].fields.depends_on number - YES - The pk of the task that the target task depends on -

Recipe

Endpoints

Method Endpoint Body Description Comments
GET /api/1.0/recipes 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.name string - YES - The name of the recipe -
[Object Root].list[].fields.version string - YES - The version of the recipe -
[Object Root].list[].fields.layer_version_id number - YES - The version of the layer in which the recipe existed at the task building time -
[Object Root].list[].fields.summary string - YES - - may be empty
[Object Root].list[].fields.description string - YES - - may be empty
[Object Root].list[].fields.section string - YES - - may be empty
[Object Root].list[].fields.license string - YES - - -
[Object Root].list[].fields.licensing_info string - YES - - may be empty
[Object Root].list[].fields.homepage string - YES - - may be empty
[Object Root].list[].fields.bugtracker string - YES - - may be empty
[Object Root].list[].fields.author string - YES - - may be empty
[Object Root].list[].fields.file_path string - YES - - -


Recipe Dependencies

Returns the package dependency data

Endpoints

Method Endpoint Body Description Comments
GET /api/1.0/recipe_dependencies 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.recipe_id number - YES - The pk of the target recipe -
[Object Root].list[].fields.depends_on_id number - YES - The pk of the recipe that the target recipe depends on -


Build Packages

  • Information collected at build time

Endpoints

Method Endpoint Body Description Comments
GET /api/1.0/packages 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 number - YES - The pk of the build that generated this package -
[Object Root].list[].fields.recipe number - YES - The pk of the recipe that generated this package -
[Object Root].list[].fields.name string - YES - The package name -
[Object Root].list[].fields.version string - YES - The package version -
[Object Root].list[].fields.revision string - YES - The package revision -
[Object Root].list[].fields.size number - YES - The size of the package, in bytes -
[Object Root].list[].fields.section string - YES - The section in which this package belongs -
[Object Root].list[].fields.license string - YES - The license of the package -
[Object Root].list[].fields.summary string - YES - The content of the recipe SUMMARY -
[Object Root].list[].fields.description string - YES - The content of the recipe DESCRIPTION -

Package Dependencies

Returns the package dependency data

Endpoints

Method Endpoint Body Description Comments
GET /api/1.0/package_dependencies 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.package number - YES - The pk of the target package -
[Object Root].list[].fields.depends_on number - YES - The pk of the package that the target package depends on Known issues: 5225
[Object Root].list[].fields.dep_type number 6 YES - Dependency type 0 RDEPENDS
1 RPROVIDES
2 RRECOMMENDS
5 RSUGGESTS
4 RREPLACES
5 RCONFLICTS

Package Files

Returns the package dependency data

Endpoints

Method Endpoint Body Description Comments
GET /api/1.0/package_files JSON Returns page size limited and search criteria filtered amount of files for a package 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.package_id number - YES - The pk of the package which this file belogs to -
[Object Root].list[].fields.path String - YES - Full path of the file -
[Object Root].list[].fields.size number - YES - The size of the file in bytes -


Variable

Endpoints

Method Endpoint Body Description Comments
GET /api/1.0/variables 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 - The pk of the build that generated this variable -
[Object Root].list[].fields.variable_name string - YES - - -
[Object Root].list[].fields.variable_value string - YES - - -
[Object Root].list[].fields.file string - YES - Path to the file that defines the variable Not currently available
[Object Root].list[].fields.changed boolean - YES - Not defined Not currently available
[Object Root].list[].fields.file string - YES - Path to the file that defines the variable Not currently available
[Object Root].list[].fields.human_readable_name boolean - YES - Not defined Not currently available
[Object Root].list[].fields.description string - YES - Variable documentation in documentation.conf


LogMessage

Endpoints

Method Endpoint Body Description Comments
GET /api/1.0/logmessages 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 - The pk of the build that generated this variable -
[Object Root].list[].fields.level number - YES - 0 - INFO
1 - WARNING
2 - ERROR
-
[Object Root].list[].fields.message string - YES - - -
[Object Root].list[].fields.pathname string - YES - Path to the file that defines the variable Not currently available
[Object Root].list[].fields.lineno number - YES - Not defined Not currently available