LAVA makes the test results available directly from the instance,
without needing to go through ``lava-tool``. The results for any test
job which the user can view can be downloaded in :abbr:`CSV
(comma-separated value)` or YAML format.

For example, the results for test job number 123 are available in CSV
format using: ``https://validation.linaro.org/results/123/csv``. The
same results for job number 123 are available in YAML format using:
``https://validation.linaro.org/results/123/yaml``

If you know the test definition name, you can also download the
results for that specific test definition only in a similar way:
``https://validation.linaro.org/results/123/0_singlenode-advanced/csv``
for the data in CSV format and
``https://validation.linaro.org/results/123/0_singlenode-advanced/yaml``
for the YAML format.

Test definition names use a prefix to show the sequence within the
test job, for each namespace. The list of test definitions within a
test job can be retrieved using the Summary:
``https://validation.linaro.org/results/123/yaml_summary``

Some test jobs can be restricted to particular users or groups of
users. The results of these test jobs will be restricted in the same
way. To download these results, you will need to specify your username
and one of your :ref:`authentication_tokens` when using the REST
API. Remember to quote the URL if using it on the command line, to
avoid the & character being mis-interpreted by your shell, for
example:

.. code-block:: shell

    $ curl 'https://validation.linaro.org/results/123/0_singlenode-advanced/yaml?user=user.name&token=yourtokentextgoeshereononeverylongline'

Use the **Username** as specified in `your Profile </me>`_ - this may
differ from the username you use if logging in via LDAP.

.. caution:: Take care of your tokens - avoid using personal tokens in
   scripts and test definitions, or any other files that end up in
   public git repositories. Wherever supported, use ``https://`` when
   using a token to avoid it being sent in plain-text.

.. index:: results - pagination

.. _test_suite_result_pagination:

Chunking test suite results
===========================

When jobs have a large number of test results in a particular test suite,
it is advisable to use test case **chunking**, to provide pagination for
downloading test cases via the REST API.

Two special query string arguments are supported for allowing users to
**chunk** the test cases when downloading test suite results.

* **Limit** - determines how many results to read in this chunk

* **offset** - the number of results already received

Limit and offset are supported only for test suite exports (both csv
and yaml). Example:

.. code-block:: shell

    $ curl 'https://validation.linaro.org/results/123/0_singlenode-advanced/yaml?limit=100&offset=200'

    $ curl 'https://validation.linaro.org/results/123/0_singlenode-advanced/yaml?user=user.name&token=yourtokentextgoeshereononeverylongline&limit=100&offset=200'

To retrieve the full count of testcases in a single test suite (useful for
pagination), you can use the testcase-count REST API method, like so:

.. code-block:: shell

    $ curl 'https://validation.linaro.org/results/123/0_singlenode-advanced/+testcase-count?user=user.name&token=yourtokentextgoeshereononeverylongline'

.. note:: Test cases will be ordered by ID regardless of whether pagination is
   used or not. This applies to downloading test cases for a particular test
   suite only.

.. index:: full rest api

.. _full_rest_api:

Full REST API
=============

.. _`django-rest-framework`:
   https://www.django-rest-framework.org

Full REST API is available with /api URL. The API is based on
`django-rest-framework`_. All of the docs from django-rest-framework apply.
LAVA uses token based authendication. To obtain a token POST request has to
be made to /api/<version>/token/ endpoint. The request has to contain
username and password fields. These are the same as used for web UI
authentication. Call returns either existing AuthToken or creates new one.
The tokens used for REST API and XML-RPC API are the same objects. Example:

.. code-block:: none

    $ curl -d '{"username":"john.doe", "password":"FooBar"}' -H "Content-Type: application/json" -X POST "https://master.lavasoftware.org/api/v0.1/token/"

Reply will contain a token that identifies the user when using the REST API:

.. code-block:: json

    {"token":"ezwpm1wytdwwnbbu90e6eo02bligzw21b0ibyc1ikbc19zkin6639f3wodce5u9oc3lndoqn0asfewrw0bclfii4mgtweokrxa0mztohj46n2rdi0qinezsbobfauqf0"}

Currently there are 3 endpoints available:
 - /api/v0.1/jobs/
 - /api/v0.1/devicetypes/
 - /api/v0.1/devices/

In addition TestJob object (/api/v0.1/jobs/id/) contains following routes:
 - logs (/api/v0.1/jobs/<job_id>/logs)
 - suites (/api/v0.1/jobs/<job_id>/suites)
 - tests (/api/v0.1/jobs/<job_id>/tests)

The results are also available in JUnit or TAP13 format at:
 - junit (/api/v0.1/jobs/<job_id>/junit/)
 - tap13 (/api/v0.1/jobs/<job_id>/tap13/)

Objects in all endpoints can be sorted as described
in django-rest-framework docs: https://www.django-rest-framework.org/api-guide/filtering/
Filtering and searching is currently disabled.

Examples specific to LAVA objects:
Sorting

.. code-block:: none

    https://master.lavasoftware.org/api/v0.1/jobs/?ordering=-start_time

Sorting fields for test jobs:
 - id
 - submit_time
 - start_time
 - end_time

Sorting fields for device types:
 - name
 - architecture
 - processor
 - cpu_model
 - aliases
 - bits
 - cores
 - core_count
 - description
 - health_frequency
 - disable_health_check
 - health_denominator
 - display
 - owners_only

Sorting fields for devices:
 - hostname
 - device_type
 - device_version
 - physical_owner
 - physical_group
 - description
 - tags
 - state
 - health
 - worker_host
