WaiverDB APIs¶

WavierDB offers a HTTP REST API.

REST API¶

GET /api/v1.0/¶: Override this method to customize the documentation page

GET /api/v1.0/about¶

Returns the current running version and the method used for authentication.

Sample response:

HTTP/1.0 200 OK
Content-Length: 55
Content-Type: application/json
Date: Tue, 31 Oct 2017 04:29:19 GMT
Server: Werkzeug/0.11.10 Python/2.7.13

{
  "auth_method": "OIDC",
  "version": "0.3.1"
}

Status Codes:

200 OK – Currently running waiverdb software version and authentication are returned.

GET /api/v1.0/config¶

Returns the current configuration (PERMISSION_MAPPING and SUPERUSERS).

Note: PERMISSION_MAPPING is deprecated, use GET /api/v1.0/permissions instead.

Sample response:

HTTP/1.0 200 OK
Content-Length: 55
Content-Type: application/json
Date: Tue, 31 Oct 2017 04:29:19 GMT
Server: Werkzeug/0.11.10 Python/2.7.13

{
  "permission_mapping": {
      "^kernel-qe": {
          "groups": ["devel", "qa"],
          "users": []
      }
  },
  "superusers": ["alice", "bob"]
}

Status Codes:

200 OK – Configuration is returned.

GET /api/v1.0/permissions¶

Returns the waiver permissions.

Each entry has “testcases” (list of glob patterns for matching test case name) and “users” or “groups”.

Optional “testcases_ignore” (similar to “testcases”) allows to ignore a permission entry on a matching test case name.

The full list of users and groups permitted to waive given test case is constructed by iterating the permissions in order and adding “users” and “groups” from each permission entry which has at least one pattern in “testcases” matching the test case name and no matching pattern in “testcases_ignore”.

Sample response:

HTTP/1.0 200 OK
Content-Length: 999
Content-Type: application/json
Server: gunicorn/20.0.4
Date: Wed, 10 Mar 2021 08:00:00 GMT

[
    {
        "name": "kernel-qe",
        "maintainers": ["alice@example.com"],
        "testcases": ["kernel-qe.*"],
        "testcases_ignore": ["kernel-qe.unwaivable.*"],
        "groups": ["devel", "qa"],
        "users": ["alice@example.com"],
    },
    {
        "name": "Greenwave Tests",
        "maintainers": ["greenwave-dev@example.com"],
        "testcases": ["greenwave-tests.*"],
        "groups": [],
        "users": ["HTTP/greenwave-dev.tests.example.com"]
    }
]

JSON Parameters:

testcase (string) – If specified, only permissions for given test case is returned.

Status Codes:

200 OK – Permissions are returned.

GET /api/v1.0/swagger.json¶: Render the Swagger specifications as JSON

POST /api/v1.0/waivers/¶

Create a new waiver or multiple waivers.

To create multiple waivers, pass list of dict instead. Response also contains list on success.

Sample request:

POST /api/v1.0/waivers/ HTTP/1.1
Host: localhost:5004
Accept-Encoding: gzip, deflate
Accept: application/json
Connection: keep-alive
User-Agent: HTTPie/0.9.4
Content-Type: application/json
Content-Length: 91

{
    "subject_type": "compose",
    "subject_identifier": "Fedora-9000-19700101.n.18",
    "testcase": "compose.install_no_user",
    "waived": false,
    "product_version": "Parrot",
    "comment": "This is fine"
}

Sample response:

HTTP/1.0 201 CREATED
Content-Length: 228
Content-Type: application/json
Date: Thu, 16 Mar 2017 17:42:04 GMT
Server: Werkzeug/0.12.1 Python/2.7.13

{
    "comment": "This is fine",
    "id": 15,
    "product_version": "Parrot",
    "subject_type": "compose",
    "subject_identifier": "Fedora-9000-19700101.n.18",
    "testcase": "compose.install_no_user",
    "scenario": null,
    "timestamp": "2017-03-16T17:42:04.209638",
    "username": "jcline",
    "waived": false,
    "proxied_by": null
}

JSON Parameters:

subject_type (string) – The type of thing which this waiver is for.
subject_identifier (string) – The identifier of the thing this waiver is for. The semantics of this identifier depend on the “subject_type”. For example, Koji builds are identified by their NVR.
testcase (string) – The result testcase for the waiver.
scenario (string) – The result scenario for the waiver.
waived (boolean) – Whether or not the result is waived.
product_version (string) – The product version string.
comment (string) – A comment explaining the waiver.
username (string) – Username on whose behalf the caller is proxying.

Status Codes:

201 Created – The waiver was successfully created.

GET /api/v1.0/waivers/¶

Get waiver records.

Sample request:

GET /api/v1.0/waivers/ HTTP/1.1
Host: localhost:5004
User-Agent: curl/7.51.0
Accept: application/json

Sample response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 184
Server: Werkzeug/0.12.1 Python/2.7.13
Date: Thu, 16 Mar 2017 13:53:14 GMT

{
    "data": [],
    "first": "http://localhost:5004/api/v1.0/waivers/?page=1",
    "last": "http://localhost:5004/api/v1.0/waivers/?page=0",
    "next": null,
    "prev": null
}

Query Parameters:

page (int) – The page to get.
limit (int) – Limit the number of items returned.
subject_type (string) – Only include waivers for the given subject type.
subject_identifier (string) – Only include waivers for the given subject identifier.
testcase (string) – Only include waivers for the given test case name.
scenario (string) – Only include waivers for the given scenario name.
product_version (string) – Only include waivers for the given product version.
username (string) – Only include waivers which were submitted by the given user.
proxied_by (string) – Only include waivers which were proxied on behalf of someone else by the given user.
since (string) – An ISO 8601 formatted datetime (e.g. 2017-03-16T13:40:05+00:00) to filter results by. Optionally provide a second ISO 8601 datetime separated by a comma to retrieve a range (e.g. 2017-03-16T13:40:05+00:00, 2017-03-16T13:40:15+00:00)
include_obsolete (boolean) – If true, obsolete waivers will be included.

Status Codes:

200 OK – If the query was valid and no problems were encountered. Note that the response may still contain 0 waivers.
400 Bad Request – The request was malformed and could not be processed.

POST /api/v1.0/waivers/+by-subjects-and-testcases¶

Deprecated. Use POST /api/v1.0/waivers/+filtered instead.

Instead of making a deprecated request like this:

POST /api/v1.0/waivers/+by-subjects-and-testcases HTTP/1.1
Content-Type: application/json

{
     "results": [
         {
             "subject": {"productmd.compose.id": "Fedora-9000-19700101.n.18"},
             "testcase": "compose.install_no_user"
         },
         {
             "subject": {"item": "gzip-1.9-1.fc28", "type": "koji_build"},
             "testcase": "dist.rpmlint"
         }
     ]
}

make the following equivalent request:

POST /api/v1.0/waivers/+filtered HTTP/1.1
Content-Type: application/json

{
     "filters": [
         {
             "subject_type": "compose",
             "subject_identifier": "Fedora-9000-19700101.n.18",
             "testcase": "compose.install_no_user"
         },
         {
             "subject_type": "koji_build",
             "subject_identifier": "gzip-1.9-1.fc28",
             "testcase": "dist.rpmlint"
         }
     ]
}

POST /api/v1.0/waivers/+filtered¶

Get waiver records, filtered by some criteria.

This API behaves the same way as GET /api/v1.0/waivers/, but it allows for longer or more complex filter criteria that cannot be expressed in the query string.

Note that the response is not paginated (that is, all waivers are returned in the ‘data’ key, even if there is a large number of them).

Sample request:

POST /api/v1.0/waivers/+filtered HTTP/1.1
Accept: application/json
Content-Type: application/json

{
     "filters": [
         {
             "subject_type": "compose",
             "subject_identifier": "Fedora-9000-19700101.n.18",
             "testcase": "compose.install_no_user"
         },
         {
             "subject_type": "koji_build",
             "subject_identifier": "gzip-1.9-1.fc28",
             "testcase": "dist.rpmlint"
         }
     ]
}

Sample response:

HTTP/1.1 200 OK
Content-Type: application/json

{
     "data": [
         {
             "id": 15,
             "comment": "The tests broke",
             "product_version": "fedora-27",
             "subject_type": "compose",
             "subject_identifier": "Fedora-9000-19700101.n.18",
             "testcase": "compose.install_no_user",
             "scenario": null,
             "timestamp": "2017-03-16T17:42:04.209638",
             "username": "jcline",
             "waived": true,
             "proxied_by": null
         }
     ]
}

JSON Parameters:

filters (list) – List of filter dicts. If the list contains multiple filter dicts, they are combined with logical OR. Within each filter dict, the criteria are combined with logical AND. Keys within the filter dict are the same as the filtering parameters accepted by GET /api/v1.0/waivers/.
include_obsolete (boolean) – If true, obsolete waivers will be included.

Status Codes:

200 OK – Returns matching waivers, if any.
400 Bad Request – The request was malformed (invalid filter critera).

GET /api/v1.0/waivers/(int: waiver_id)¶

Get a single waiver by waiver ID.

Parameters:

waiver_id (int) – The waiver’s database ID.

Status Codes:

200 OK – The waiver was found and returned.
404 Not Found – No waiver exists with that ID.

POST /api/v1.0/waivers/create¶

Create a new waiver or multiple waivers.

To create multiple waivers, pass list of dict instead. Response also contains list on success.

Sample request:

POST /api/v1.0/waivers/ HTTP/1.1
Host: localhost:5004
Accept-Encoding: gzip, deflate
Accept: application/json
Connection: keep-alive
User-Agent: HTTPie/0.9.4
Content-Type: application/json
Content-Length: 91

{
    "subject_type": "compose",
    "subject_identifier": "Fedora-9000-19700101.n.18",
    "testcase": "compose.install_no_user",
    "waived": false,
    "product_version": "Parrot",
    "comment": "This is fine"
}

Sample response:

HTTP/1.0 201 CREATED
Content-Length: 228
Content-Type: application/json
Date: Thu, 16 Mar 2017 17:42:04 GMT
Server: Werkzeug/0.12.1 Python/2.7.13

{
    "comment": "This is fine",
    "id": 15,
    "product_version": "Parrot",
    "subject_type": "compose",
    "subject_identifier": "Fedora-9000-19700101.n.18",
    "testcase": "compose.install_no_user",
    "scenario": null,
    "timestamp": "2017-03-16T17:42:04.209638",
    "username": "jcline",
    "waived": false,
    "proxied_by": null
}

JSON Parameters:

subject_type (string) – The type of thing which this waiver is for.
subject_identifier (string) – The identifier of the thing this waiver is for. The semantics of this identifier depend on the “subject_type”. For example, Koji builds are identified by their NVR.
testcase (string) – The result testcase for the waiver.
scenario (string) – The result scenario for the waiver.
waived (boolean) – Whether or not the result is waived.
product_version (string) – The product version string.
comment (string) – A comment explaining the waiver.
username (string) – Username on whose behalf the caller is proxying.

Status Codes:

201 Created – The waiver was successfully created.

GET /api/v1.0/waivers/create¶: Deprecated, kept as a redirect for a backward compatibility

GET /api/v1.0/waivers/new¶

HTML form to create a waiver.

Default form input field values can be passed as request query parameters.

Query Parameters:

subject_type (string) – The type of thing which this waiver is for.
subject_identifier (string) – The identifier of the thing this waiver is for. The semantics of this identifier depend on the “subject_type”. For example, Koji builds are identified by their NVR.
testcase (string) – The result testcase for the waiver.
scenario (string) – The result scenario for the waiver.
product_version (string) – The product version string.
comment (string) – A comment explaining the waiver.

Status Codes:

200 OK – The HTML with the form is returned.

GET /api/v1.0/waivers/new/new_waiver.js¶: Provides a JS for a new waiver form

GET /healthcheck¶

Request handler for performing an application-level health check. This is not part of the published API, it is intended for use by OpenShift or other monitoring tools.

Returns a 200 response if the application is alive and able to serve requests.

GET /swaggerui/(path: filename)¶

The view function used to serve files from static_folder. A route is automatically registered for this view at static_url_path if static_folder is set.

Note this is a duplicate of the same method in the Flask class.

Added in version 0.5.

WaiverDB APIs¶

REST API¶

WaiverDB

Navigation

Related Topics