Client

There are two ways to interact with openQA as a user. The web UI and the REST API. In this guide we will focus on the latter. You've probably already seen a few examples of its use with openqa-cli earlier in the documentation.

Here we will start again from the very beginning to give you a more complete overview of its capabilities. To get started all you need is an openQA instance with a few jobs and curl. Just replace openqa.example.com in the examples below with the hostname of your openQA instance.

curl http://openqa.example.com/api/v1/jobs/overview

That one-liner will show you the latest jobs from the overview in JSON format. You could also append various query parameters to filter the jobs further.

curl http://openqa.example.com/api/v1/jobs/overview?result=failed

But using curl directly can also get a bit clunky when the data you need to submit is more complex, you want to store host and authentication information in config files, or just get the returned JSON pretty printed.

For those cases openQA also contains a dedicated client to help you with that. It is called openqa-cli and can usually be installed with an openQA-client package (the name will vary depending on your Linux distribution).

openqa-cli api --host http://openqa.example.com jobs/overview result=failed

Our example above is quickly translated. The api subcommand of openqa-cli allows you to perform arbitrary HTTP requests against the REST API. The path will automatically get the correct version prefix applied (such as /api/v1), and query parameters can be passed along as key=value pairs.

Help

The api subcommand is not the only one available and more will be added over time. To get a complete list of all currently available subcommands you can use the --help option.

openqa-cli --help

And each subcommand also contains descriptions for all its available options, as well as many common usage examples.

openqa-cli api --help

Authentication

Not all REST endpoints are public, many will return a 403 Forbidden error if you try to access them without proper credentials. The credentials (or API keys) are managed in the web UI, to which you will need operator access.

Once you have acquired a valid key and secret you can store them in a config file or use them ad-hoc from the command line. There are two config files openqa-cli will try, the global /etc/openqa/client.conf, and your personal ~/.config/openqa/client.conf. The format is the same for both.

[openqa.example.com]
key = 1234567890ABCDEF
secret = ABCDEF1234567890

Alternatively specify key and secret in environment variables OPENQA_API_KEY and OPENQA_API_SECRET. For ad-hoc use all openqa-cli subcommands use the --apikey and --apisecret options which will override whatever the environment or config files may contain.

openqa-cli api --host http://openqa.example.com --apikey 1234567890ABCDEF \
    --apisecret ABCDEF1234567890 -X POST jobs/2/comments text=hello

Personal access token

The authentication mechanism used by openqa-cli was specifically designed to allow secure access to the REST API even via unencrypted HTTP connections. But when your openQA server has been deployed with HTTPS (and for HTTP connections originating from localhost) you can also use plain old Basic or Bearer token authentication with a personal access token. That allows for almost any HTTP client to be used with openQA.

This access token is made up of your username, and the same key/secret combo the openqa-cli authentication mechanism uses. All you have to do is combine them as USERNAME:KEY:SECRET and you can use curl to access operator and admin REST endpoints (depending on user privileges of course).

curl -u arthur:1234567890ABCDEF:ABCDEF1234567890 -X DELETE \
    https://openqa.example.com/api/v1/assets/1

And for HTTP clients that don't support Basic authentication or where the use of plain HTTP headers might be more convenient, you can also send the personal access token in the form of a Bearer token.

curl -H 'Authorization: Bearer arthur:1234567890ABCDEF:ABCDEF1234567890'\
    -X DELETE https://openqa.example.com/api/v1/assets/1

When using curl or wget one can utilise the ~/.netrc file to automatically add those credentials. See the following template for openqa.example.com and the user arthur

machine openqa.example.com login arthur password 1234567890ABCDEF:ABCDEF1234567890

For curl one needs to use curl --netrc. For wget it's wget --auth-no-challenge so that wget will provide the access credentials without being explicitly asked.

Features

Many of the openqa-cli api features are designed to be similar to other commonly used tools like curl. It helps a lot if you are already familiar with the HTTP protocol and JSON. Both will be referenced extensively.

HTTP Methods

The --method option (or -X for short) allows you to change the HTTP request method from GET to something else. In the openQA API you will most commonly encounter POST, PUT and DELETE. For example to start testing a new ISO image you would use POST.

openqa-cli api --host http://openqa.example.com -X POST isos \
    ISO=openSUSE-Factory-NET-x86_64-Build0053-Media.iso DISTRI=opensuse \
    VERSION=Factory FLAVOR=NET ARCH=x86_64 BUILD=0053

HTTP Headers

With the --header option (or -a for short) you can add one or more custom HTTP headers to your request. This feature is currently not used much, but can be handy if for example the REST endpoint you are using supports content negotiation.

openqa-cli api --host http://openqa.example.com -a 'Accept: application/json' \
    jobs/overview

HTTP Body

To change the HTTP request body there are multiple options available. The simplest being --data (or -d for short), which allows you to use a plain string as request body. This can be useful for example to change the group id of a job.

openqa-cli api --host http://openqa.example.com -X PUT jobs/1 \
    --data '{"group_id":2}'

With the --data-file option (or -D for short) you can also use a file instead.

openqa-cli api --host http://openqa.example.com -X PUT jobs/1 \
    --data-file ./test.json

Or just pipe the data to openqa-cli.

echo '{"group_id":2}' | openqa-cli api --host http://openqa.example.com -X PUT \
    jobs/1

Forms

Most data you pass to the openQA API will be key/value form parameters. Either in the query string, or encoded as application/x-www-form-urlencoded HTTP request body. But you don't have to worry about this too much, because openqa-cli api knows when to use which format automatically, you just provide the key/value pairs.

Form parameters are most commonly passed as additional arguments after the path. For example to post a comment to a job.

openqa-cli api --host http://openqa.example.com -X POST jobs/2/comments text=abc

This value can also be quoted to include whitespace characters.

openqa-cli api --host http://openqa.example.com -X POST jobs/2/comments \
    text="Hello openQA!"

And you can use interpolation to include files.

openqa-cli api --host http://openqa.example.com -X POST jobs/2/comments \
    text="$(cat ./comment.markdown)"

Alternatively you can also use the --form option (or -f for short) to provide all form parameters in JSON format. Here you would reuse the HTTP body options, such as --data and --data-file, to pass the JSON document to be turned into form parameters.

openqa-cli api --host http://openqa.example.com --form --data '{"text":"abc"}' \
    -X POST jobs/2/comments

JSON

The primary data exchange format in the openQA API is JSON. And you will even see error messages in JSON format most of the time.

{"error":"no api key","error_status":403}

By default the returned JSON is often compressed, for better performance, and can be hard to read if the response gets larger. But if you add the --pretty option (or -p for short), openqa-cli can reformat it for you.

openqa-cli api --host http://openqa.example.com --pretty jobs/overview

The JSON will be re-encoded with newlines and indentation for much better readability.

{
   "error" : "no api key",
   "error_status" : 403
}

The --json option (or -j for short) can be used to set a Content-Type: application/json request header. Whenever you need to upload a JSON document.

openqa-cli api --host http://openqa.example.com -X PUT jobs/1 --json \
    --data '{"group_id":2}'

Unicode

Just use a UTF-8 locale for your terminal and Unicode will pretty much just work.

openqa-cli api --host http://openqa.example.com -X POST jobs/2/comments \
    text="I ♥ Unicode"

JSON documents are always expected to be UTF-8 encoded.

openqa-cli api --host http://openqa.example.com --form \
    --data '{"text":"I ♥ Unicode"}' -X POST jobobs/407/comments \
    -X POST jobs/2/comments

Host shortcuts

Aside from the --host option, there are also a few shortcuts available. If you leave out the --host option completely, the default value will be http://localhost, which is very convenient for debugging purposes.

openqa-cli api jobs/overview

And organisations that contribute to openQA and are invested in the project can also get their very own personalised shortcuts. Currently we have --osd for http://openqa.suse.de, and --o3 for openqa.opensuse.org.

openqa-cli api --o3 jobs/overview

Debugging

Often times just seeing the HTTP response body might not be enough to debug a problem. With the --verbose option (or -v for short) you can also get additional information printed.

openqa-cli api --host http://openqa.example.com --verbose -X POST \
    jobs/407/comments text="Hello openQA!"

This includes the HTTP response status line, as well as headers.

HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8
Strict-Transport-Security: max-age=31536000; includeSubDomains
Server: Mojolicious (Perl)
Content-Length: 41
Date: Wed, 29 Apr 2020 12:03:11 GMT

{"error":"no api key","error_status":403}

And if that is not enough, you can experiment with the MOJO_CLIENT_DEBUG environment variable.

MOJO_CLIENT_DEBUG=1 openqa-cli api --host http://openqa.example.com -X POST \
    jobs/407/comments text="Hello openQA!"

It will activate a debug feature in the Mojolicious framework, which openQA uses internally, and show everything that is being sent or received.

POST /api/v1/jobs/407/comments HTTP/1.1
Content-Length: 20
User-Agent: Mojolicious (Perl)
Content-Type: application/x-www-form-urlencoded
Host: openqa.example.com
X-API-Microtime: 1588153057
X-API-Hash: 8a73f6c37920921d52a8b5352ab417d923ee979e
Accept-Encoding: gzip
X-API-Key: AAEAC3E147A1EEE0
Accept: application/json

text=Hello+openQA%21

Just be aware that this is a feature the openQA team does not control, and the exact output as well as how it escapes control characters will change a bit over time.

Archiving individual job results

With the archive subcommand of openqa-cli you can download all the assets and test results of a job for archiving or debugging purposes.

openqa-cli archive --host http://openqa.example.com 408 /tmp/openqa_job_408

Thumbnails are not included by default, but can be added with the --with-thumbnails option (or -t for short).

openqa-cli archive --host http://openqa.example.com --with-thumbnails \
    408 ~/openqa_job_408

See also Archiving for automatic archiving of old jobs.