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.

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": {"productmd.compose.id": "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": {"productmd.compose.id": "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** (*object*) -- The result subject for the waiver.

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

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** (*dict*) -- Only include waivers for the given
        subject.

      * **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/+by-subjects-and-testcases

   Return a list of waivers by filtering the waivers with a list of
   result subjects and testcases. This accepts POST requests in order
   to handle a special case where a GET /waivers/ request has a long
   query string with many result subjects/testcases that could cause
   413 errors.

   **Sample request**:

      POST /api/v1.0/waivers/+by-subjects-and-testcases 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: 40

      {
           "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"
               }
           ]
      }

   **Sample response**:

      HTTP/1.0 200 OK
      Content-Length: 562
      Content-Type: application/json
      Date: Thu, 21 Sep 2017 04:58:37 GMT
      Server: Werkzeug/0.11.10 Python/2.7.13

      {
          "data": [
              {
                  "comment": "This is fine",
                  "id": 5,
                  "product_version": "Parrot",
                  "subject": {"productmd.compose.id": "Fedora-9000-19700101.n.18"},
                  "testcase": "compose.install_no_user",
                  "timestamp": "2017-09-21T04:55:53.343368",
                  "username": "dummy",
                  "waived": true,
                  "proxied_by": null
              },
              {
                  "comment": "This is fine",
                  "id": 4,
                  "product_version": "Parrot",
                  "subject": {"item": "gzip-1.9-1.fc28", "type": "koji_build"},
                  "testcase": "dist.rpmlint",
                  "timestamp": "2017-09-21T04:55:51.936658",
                  "username": "dummy",
                  "waived": true,
                  "proxied_by": null
              }
          ]
      }

   JSON Parameters:
      * **results** (*array*) -- Filter the waivers by a list of
        dictionaries with result subjects and testcase.

      * **product_version** (*string*) -- Filter the waivers by
        product version.

      * **username** (*string*) -- Filter the waivers by username.

      * **proxied_by** (*string*) -- Filter the waivers by the users
        who are allowed to create waivers on behalf of other users.

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

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.
