waiverdb - Man Page

waiverdb — WaiverDB Rest API

WavierDB offers a HTTP Rest API.

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).

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

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",
    "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.
• 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.

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",
             "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.

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.

Red Hat, Inc. and others

2020, Red Hat, Inc. and others