WaiverDB APIs
*************

WavierDB offers a HTTP REST API.


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.
