Analysis REST API Contracts

• Implementation in progress.

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 via an unrestricted, 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, Target, Target installed packages, Layer, Layer version, Task, Task dependencies, Recipe, Recipe dependencies, Build packages, Package dependencies, Package files, 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 be 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 determines the sorting of the results.	"<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 builds from the database	-

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 reference to its 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 Failed build 1 Successful build
[Object Root].list[].fields.build_name	string	-	YES	-	Build name	Known issues: 5187
[Object Root].list[].fields.machine	string	-	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.image_fstypes	string	-	YES	-	The file types create by this build	Space-separated file name suffixes. Known issues: 5188
[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 a build target(s).

Endpoints

Method	Endpoint	Body	Description	Comments
GET	/api/1.0/targets	JSON	Returns page size-limited and search criteria-filtered targets from the database	-

Response

Name	Type	Dimension	Required	Default value(s)	Description	Comments
[Object Root]	object	-	YES	-	-	-
[Object Root].count	number	-	YES	-	Total amount of targets to be displayed (according to filter parameter)	-
[Object Root].list	object array	-	YES	-	-	To describe a generic object element of the array, the reference to its 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.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	Know issues: 5191

Target installed packages

Returns information about the packages installed in a target, when such target is an image recipe.

NOTE: Build history must be enabled to collect this information.

Endpoints

Method	Endpoint	Body	Description	Comments
GET	/api/1.0/target_packages	JSON	Returns page size-limited and search criteria-filtered installed packages from the database	-

Response

Name	Type	Dimension	Required	Default value(s)	Description	Comments
[Object Root]	object	-	YES	-	-	-
[Object Root].count	number	-	YES	-	Total amount of packages to be displayed (according to filter parameter)	-
[Object Root].list	object array	-	YES	-	-	To describe a generic object element of the array, the reference to its 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 used in the builds recorded by Toaster.

Endpoints

Method	Endpoint	Body	Description	Comments
GET	/api/1.0/layers	JSON	Returns page size-limited and search criteria-filtered layers from the database	-

Response

Name	Type	Dimension	Required	Default value(s)	Description	Comments
[Object Root]	object	-	YES	-	-	-
[Object Root].count	number	-	YES	-	Total amount of layers to be displayed (according to filter parameter)	-
[Object Root].list	object array	-	YES	-	-	To describe a generic object element of the array, the reference to its 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

Returns information about the 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 layers from the database	-

Response

Name	Type	Dimension	Required	Default value(s)	Description	Comments
[Object Root]	object	-	YES	-	-	-
[Object Root].count	number	-	YES	-	Total amount of layers to be displayed (according to filter parameter)	-
[Object Root].list	object array	-	YES	-	-	To describe a generic object element of the array, the reference to its 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 tasks from the database	-

Response

Name	Type	Dimension	Required	Default value(s)	Description	Comments
[Object Root]	object	-	YES	-	-	-
[Object Root].count	number	-	YES	-	Total amount of tasks to be displayed (according to filter parameter)	-
[Object Root].list	object array	-	YES	-	-	To describe a generic object element of the array, the reference to its 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	6	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.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.disk_io	number	-	NO	-	Time spent by the task in I/O operations (in ms)
[Object Root].list[].fields.cpu_usage	number	-	NO	-	Percent of the CPU used during the task
[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 tasks dependency data.

Endpoints

Method	Endpoint	Body	Description	Comments
GET	/api/1.0/task_dependencies	JSON	Returns page size-limited and search criteria-filtered tasks from the database	-

Response

Name	Type	Dimension	Required	Default value(s)	Description	Comments
[Object Root]	object	-	YES	-	-	-
[Object Root].count	number	-	YES	-	Total amount of tasks to be displayed (according to filter parameter)	-
[Object Root].list	object array	-	YES	-	-	To describe a generic object element of the array, the reference to its 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

Returns information about recipes in a certain build.

Endpoints

Method	Endpoint	Body	Description	Comments
GET	/api/1.0/recipes	JSON	Returns page size-limited and search criteria-filtered recipes from the database	-

Response

Name	Type	Dimension	Required	Default value(s)	Description	Comments
[Object Root]	object	-	YES	-	-	-
[Object Root].count	number	-	YES	-	Total amount of recipes to be displayed (according to filter parameter)	-
[Object Root].list	object array	-	YES	-	-	To describe a generic object element of the array, the reference to its 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 recipe name	-
[Object Root].list[].fields.version	string	-	YES	-	The recipe version	-
[Object Root].list[].fields.layer_version	number	-	YES	-	The version of the layer in which the recipe existed at the task building time	-
[Object Root].list[].fields.summary	string	-	YES	-	The content of the SUMMARY variable	-
[Object Root].list[].fields.description	string	-	YES	-	The content of the DESCRIPTION variable	-
[Object Root].list[].fields.section	string	-	YES	-	The section to which the recipe belongs	-
[Object Root].list[].fields.license	string	-	YES	-	The license of the recipe	-
[Object Root].list[].fields.licensing_info	string	-	YES	-	The directory containing the recipe license files	Known issues: 5194
[Object Root].list[].fields.homepage	string	-	YES	-	The website for the software provided by the recipe	-
[Object Root].list[].fields.bugtracker	string	-	YES	-	The bug tracking website for the software provided by the recipe	-
[Object Root].list[].fields.author	string	-	YES	-	The author of the recipe	-
[Object Root].list[].fields.file_path	string	-	YES	-	Path to the recipe .bb file	-

Recipe dependencies

Returns the recipe dependency data.

Endpoints

Method	Endpoint	Body	Description	Comments
GET	/api/1.0/recipe_dependencies	JSON	Returns page size-limited and search criteria-filtered recipes from the database	-

Response

Name	Type	Dimension	Required	Default value(s)	Description	Comments
[Object Root]	object	-	YES	-	-	-
[Object Root].count	number	-	YES	-	Total amount of recipes to be displayed (according to filter parameter)	-
[Object Root].list	object array	-	YES	-	-	To describe a generic object element of the array, the reference to its 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	number	-	YES	-	The PK of the target recipe	-
[Object Root].list[].fields.depends_on	number	-	YES	-	The PK of the recipe that the target recipe depends on	-
[Object Root].list[].fields.dep_type	number	2	YES	-	Dependency type	0 DEPENDS 1 RDEPENDS Known issues: 5195

Build packages

Returns data about packages built. This information is collected at build time, while target installed packages information is collected from build history.

Endpoints

Method	Endpoint	Body	Description	Comments
GET	/api/1.0/packages	JSON	Returns page size-limited and search criteria-filtered packages from the database	-

Response

Name	Type	Dimension	Required	Default value(s)	Description	Comments
[Object Root]	object	-	YES	-	-	-
[Object Root].count	number	-	YES	-	Total amount of packages to be displayed (according to filter parameter)	-
[Object Root].list	object array	-	YES	-	-	To describe a generic object element of the array, the reference to its 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 to 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 packages from the database	-

Response

Name	Type	Dimension	Required	Default value(s)	Description	Comments
[Object Root]	object	-	YES	-	-	-
[Object Root].count	number	-	YES	-	Total amount of packages to be displayed (according to filter parameter)	-
[Object Root].list	object array	-	YES	-	-	To describe a generic object element of the array, the reference to its 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 data about package-generated files.

Endpoints

Method	Endpoint	Body	Description	Comments
GET	/api/1.0/package_files	JSON	Returns page size-limited and search criteria-filtered files for a package from the database	-

Response

Name	Type	Dimension	Required	Default value(s)	Description	Comments
[Object Root]	object	-	YES	-	-	-
[Object Root].count	number	-	YES	-	Total amount of files to be displayed (according to filter parameter)	-
[Object Root].list	object array	-	YES	-	-	To describe a generic object element of the array, the reference to its 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.bpackage	number	-	YES	-	The PK of the package generating the file	-
[Object Root].list[].fields.path	String	-	YES	-	Full file path	-
[Object Root].list[].fields.size	number	-	YES	-	File size, in bytes	-

Variables

Returns data about key-value pairs applied to a certain build.

Endpoints

Method	Endpoint	Body	Description	Comments
GET	/api/1.0/variables	JSON	Returns page size-limited and search criteria-filtered variables from the database	-

Response

Name	Type	Dimension	Required	Default value(s)	Description	Comments
[Object Root]	object	-	YES	-	-	-
[Object Root].count	number	-	YES	-	Total amount of variables to be displayed (according to filter parameter)	-
[Object Root].list	object array	-	YES	-	-	To describe a generic object element of the array, the reference to its 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 variable	-
[Object Root].list[].fields.variable_name	string	-	YES	-	The key in a key-value pair	-
[Object Root].list[].fields.variable_value	string	-	YES	-	The value in a key-value pair	-
[Object Root].list[].fields.file	string	-	YES	-	Path to the file that defines the variable	Not currently available (see 5227)
[Object Root].list[].fields.changed	boolean	-	YES	-	Not defined	Not currently available
[Object Root].list[].fields.human_readable_name	string	-	YES	-	Not defined	Not currently available
[Object Root].list[].fields.description	string	-	YES	-	Variable description in documentation.conf	Known issues: 5198

Log messages

Returns data about errors / warnings thrown by the build.

Endpoints

Method	Endpoint	Body	Description	Comments
GET	/api/1.0/logmessages	JSON	Returns page size-limited and search criteria-filtered messages from the database	-

Response

Name	Type	Dimension	Required	Default value(s)	Description	Comments
[Object Root]	object	-	YES	-	-	-
[Object Root].count	number	-	YES	-	Total amount of messages to be displayed (according to filter parameter)	-
[Object Root].list	object array	-	YES	-	-	To describe a generic object element of the array, the reference to its 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 message	-
[Object Root].list[].fields.level	number	3	YES	-	Message type	0 - INFO 1 - WARNING 2 - ERROR
[Object Root].list[].fields.message	string	-	YES	-	The message content	-
[Object Root].list[].fields.pathname	string	-	YES	-	Path to the file generating the message	-
[Object Root].list[].fields.lineno	number	-	YES	-	Line number generating the message	-