Analysis REST API Contracts

• • 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/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	-	-	-

Package

• package collection happens only on building images
• the detailed package information will not be collected unless buildhistory is enabled

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_id	number	-	YES	-	The pk of the build that generated this package	-
[Object Root].list[].fields.recipe_id	number	-	YES	-	The pk of the recipe that generated this package	-
[Object Root].list[].fields.name	string	-	YES	-	-	-
[Object Root].list[].fields.version	string	-	YES	-	-	-
[Object Root].list[].fields.size	number	-	YES	-	The size of the package, 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