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

WavierDB offers a HTTP REST API.


REST API
========

POST /api/v1.0/waivers/

   Create a new waiver.

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

      {
          "result_id": 1,
          "waived": false,
          "product_version": "Parrot",
          "comment": "It's dead!"
      }

   **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": "It's dead!",
          "id": 15,
          "product_version": "Parrot",
          "result_id": 1,
          "timestamp": "2017-03-16T17:42:04.209638",
          "username": "jcline",
          "waived": false
      }

   JSON Parameters:
      * **result_id** (*int*) – The result ID 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.

   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.

      * **result_id** (*int*) – Filter the waivers by result ID.
        Accepts one or more result IDs separated by commas.

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

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

      * **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-result-ids

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

   **Sample request**:

      POST /api/v1.0/waivers/+by-result-ids 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

      {
          "result_ids": [1,2]
      }

   **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": "It's dead!",
                  "id": 5,
                  "product_version": "Parrot",
                  "result_id": 2,
                  "timestamp": "2017-09-21T04:55:53.343368",
                  "username": "dummy",
                  "waived": true
              },
              {
                  "comment": "It's dead!",
                  "id": 4,
                  "product_version": "Parrot",
                  "result_id": 1,
                  "timestamp": "2017-09-21T04:55:51.936658",
                  "username": "dummy",
                  "waived": true
              }
          ]
      }

   JSON Parameters:
      * **result_ids** (*array*) – Filter the waivers by a list of
        result IDs.

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

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

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