This plugin provides Squash TM with REST-like services, that allows you to get a JSON-type response as a result of the execution of an SQL query of type SELECT pre-given in a configuration file, sent via HTTP requests.

Overview

In general, here is what you are able/unable to do with this version (5.0.0.RELEASE) of the API REST Reports:

What you can do with it

  • execute a query defined in configuration file via its name and obtain the result based on the database of your current instance Squash.

  • add appropriate parameters values for an SQL query that requires them before sending

  • have a json file that lists all available query names

  • benefit from this present documentation

What you cannot do with it

  • create your own query and sent it for the execution

  • have support for issues

Usage

Base URL

The API publishes its services under the root URL {squash root url}/api/rest/reports/latest/.
So in a common case, it could be http://localhost:8080/squash/api/rest/reports/latest/.

API versioning

For now, no versioning of the API is planned. As it stands, the plugin is not ready for multiple concurrent deployment.

Supported HTTP methods

The API supports the following methods (verbs):

Table 1. HTTP methods
Method Usage

GET

Requests information from the server

HTTP status codes

The system replies with conventional HTTP statuses, here is a short reminder:

Table 2. HTTP status
Status Meaning

200 OK

The operation completed successfully.

204 No Content

The operation completed successfully and the server returned no response body.

400 Bad Request

The request is malformed.

401 Unauthorized

The user is not authenticated, or supplied wrong credentials.

403 Forbidden

The user’s request is denied.

404 Not Found

The resource doesn’t exist.

500 Internal Server Error

An error occured while the request was processed.

Response format

The only format supported by the API is JSON. This implies that HTTP requests to and from the API may forgo the headers Accept: application/json and Content-Type: application/json (even if they are accepted and formally correct).

Authentication

REST client should use the Basic Authentication. Remember that this protocol is considered as insecure if it is used without encryption.

This plugin requires an Authentication as Admin for execution.

Note If you prefer to explore the API using your browser, the session cookie obtained via the login page will also be valid.

Pagination parameters

When the requested query returns a collection of information, the result often comes with a pagination feature. We call them the paginated resources.

Pagination allows you to define pages of results and browse from one page to another, instead of simply retrieving all the data in one row. It is actually enabled by default.

Pagination is driven by a couple of parameters appended to the resource URI:

  • size: it is an integer that defines how many elements should be returned by page. Of course, it should be of at least 1 and may have arbitrary large value. The default value is 20.

  • page: it shows you the page you are requesting. Pages are numbered from 0 onward. Negative value will be treated as 0. Default value is 0 (which corresponds to the first page).

Paginated resources are often served with extra attributes _links and page to guide you through your navigation.

Example of a paginated query:
curl 'http://localhost:8080/squash/api/rest/reports/latest/request?name=test-cases&page=2&size=1' -i -H 'Accept: application/json'


{
    "content": [
        {
            "tcln_id": 2,
            "version": 1,
            "execution_mode": "MANUAL",
            "importance": "LOW",
            "importance_auto": false,
            "prerequisite": "",
            "reference": "123",
            "ta_test": null,
            "tc_status": "WORK_IN_PROGRESS",
            "tc_nature": 12,
            "tc_type": 20,
            "automatable": "M",
            "uuid": "27fdc633-0ade-49b3-b93d-7af3326bf69d",
            "automated_test_reference": null,
            "automated_test_technology": null,
            "scm_repository_id": null
        }
    ],
    "page": {
        "size": 1,
        "number": 2,
        "totalElements": 6,
        "totalPages": 6
    }
}

Exporting

The query execution results can be directly downloaded by adding '/export' at the end of the URI (before the request parameters).

An extra parameter named format can be added to URI to define the format of the export file. There are four available formats: txt, csv, xls and xlsx. (By default, the export format is txt)

Example of a query exported in text file:
curl 'http://localhost:8080/squash/api/rest/reports/latest/request/export?name=test-cases&format=txt' -i -H 'Accept: application/json'