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"}],
          "verbose": true
      }

   **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_satisfied": 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'
              }
          ],
          "results": [
              {
                'data': {
                  'arch': [ 'i386' ],
                  'item': [ 'cross-gcc-7.0.1-0.3.fc26' ],
                  'scenario': [ 'i386' ],
                  'type': [ 'koji_build' ]
                },
                'groups': [ '05078932-67a1-11e7-b290-5254008e42f6' ],
                'href': 'https://taskotron.fedoraproject.org/resultsdb_api/api/v2.0/results/123',
                'id': 123,
                'note': null,
                'outcome': 'FAILED',
                'ref_url': 'https://taskotron.fedoraproject.org/artifacts/all/05078932-67a1-11e7-b290-5254008e42f6/task_output/cross-gcc-7.0.1-0.3.fc26.i386.log',
                'submit_time': '2017-07-13T08:15:14.474984',
                'testcase': {
                  'href': 'https://taskotron.fedoraproject.org/resultsdb_api/api/v2.0/testcases/dist.depcheck',
                  'name': 'dist.depcheck',
                  'ref_url': 'https://fedoraproject.org/wiki/Taskotron/Tasks/depcheck'
                }
              }
          ],
          "waivers": [
              {
                'username': 'ralph',
                'comment': 'This is fine.',
                'product_version': 'fedora-27',
                'waived': true,
                'timestamp': '2018-01-23T18:02:04.630122',
                'proxied_by': null,
                'subject': [{'item': 'cross-gcc-7.0.1-0.3.fc26', 'type': 'koji_build'}],
                'testcase': 'dist.rpmlint',
                'id': 1
              }
          ],
      }

   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”}].

      * **verbose** (*bool*) – A flag to return additional
        information.

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

OPTIONS /api/v1.0/decision

   Handles the OPTIONS requests to the /decision endpoint.

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.
