Greenwave APIs
**************

Greenwave is a web application built using Flask and SQLAlchemy.

It provides a HTTP REST API for applications to use.


HTTP REST API
=============

POST /api/v1.0/decision

   Make a decision after evaluating all applicable policies based on
   test results. The request must be *application/json*.

   **Sample request**:

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

      {
          "decision_context": "bodhi_update_push_stable",
          "product_version": "fedora-26",
          "subject": [{"item": "glibc-1.0-1.f26", "type": "koji_build"}]
      }

   **Sample response**:

      HTTP/1.0 200
      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

      {
          "policies_satisified": false,
          "summary": "2 of 15 required tests failed",
          "applicable_policies": ["1"],
          "unsatisfied_requirements": [
              {
                  'item': {"item": "glibc-1.0-1.f26", "type": "koji_build"},
                  'result_id': "123",
                  'testcase': 'dist.depcheck',
                  'type': 'test-result-failed'
              },
              {
                  'item': {"item": "glibc-1.0-1.f26", "type": "koji_build"},
                  'result_id': "124",
                  'testcase': 'dist.rpmlint',
                  'type': 'test-result-missing'
              }
          ]
      }

   JSON Parameters:
      * **product_version** (*string*) -- The product version string
        used for querying WaiverDB.

      * **decision_context** (*string*) -- The decision context
        string, identified by a free-form string label. It is to be
        named through coordination between policy author and calling
        application, for example "bodhi_update_push_stable".

      * **subject** (*list*) -- A list of items about which the
        caller is requesting a decision used for querying ResultsDB.
        Each item contains one or more key-value pairs of 'data' key
        in ResultsDB API. For example, [{"type": "koji_build", "item":
        "xscreensaver-5.37-3.fc27"}].

      * **ignore_result** (*list*) -- A list of result ids that will
        be ignored when making the decision.

      * **ignore_waiver** (*list*) -- A list of waiver ids that will
        be ignored when making the decision.

   Status Codes:
      * 200 OK -- A decision was made.

      * 400 Bad Request -- Invalid data was given.

GET /api/v1.0/policies

   Returns all currently loaded policies.

   **Sample response**:

      HTTP/1.0 200
      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

      {
          "policies": [
              {
                  "id": "taskotron_release_critical_tasks",
                  "decision_context": "bodhi_update_push_stable",
                  "product_versions": [
                      "fedora-26"
                  ],
                  "rules": [
                      {
                          "test_case_name": "dist.abicheck",
                          "rule": "PassingTestCaseRule"
                      },
                      {
                          "test_case_name": "dist.rpmdeplint",
                          "rule": "PassingTestCaseRule"
                      },
                      {
                          "test_case_name": "dist.upgradepath",
                          "rule": "PassingTestCaseRule"
                      }
                  ]
              }
          ]
      }

   Status Codes:
      * 200 OK -- Currently loaded policies are returned.

GET /api/v1.0/version

   Returns the current running version.

   **Sample response**:

      HTTP/1.0 200
      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

      {
          'version': '1.2.3'
      }

   Status Codes:
      * 200 OK -- Currently running greenwave software version is
        returned.
