.. docbookrestapi

============
 V2 Web API
============

Capabilities
============

The Capabilities API allows you to directly discover which functions from the
V2 API functionality, including the selectable aggregate functions, are
supported by the currently configured storage driver. A capabilities query
returns a flattened dictionary of properties with associated boolean values -
a 'False' or absent value means that the corresponding feature is not
available in the backend.

.. rest-controller:: aodh.api.controllers.v2.capabilities:CapabilitiesController
   :webprefix: /v2/capabilities

.. autotype:: aodh.api.controllers.v2.capabilities.Capabilities
   :members:

.. _alarms-api:

Alarms
======

.. rest-controller:: aodh.api.controllers.v2.alarms:AlarmsController
   :webprefix: /v2/alarms

.. rest-controller:: aodh.api.controllers.v2.alarms:AlarmController
   :webprefix: /v2/alarms

.. autotype:: aodh.api.controllers.v2.alarms.Alarm
   :members:

.. autotype:: aodh.api.controllers.v2.alarm_rules.threshold.AlarmThresholdRule
   :members:

.. autotype:: aodh.api.controllers.v2.alarm_rules.combination.AlarmCombinationRule
   :members:

.. autotype:: aodh.api.controllers.v2.alarm_rules.gnocchi.MetricOfResourceRule
   :members:

.. autotype:: aodh.api.controllers.v2.alarm_rules.gnocchi.AggregationMetricByResourcesLookupRule
   :members:

.. autotype:: aodh.api.controllers.v2.alarm_rules.gnocchi.AggregationMetricsByIdLookupRule
   :members:

.. autotype:: aodh.api.controllers.v2.alarms.AlarmTimeConstraint
   :members:

.. autotype:: aodh.api.controllers.v2.alarms.AlarmChange
   :members:

Filtering Queries
=================

The filter expressions of the query feature operate on the fields of *Alarm*
and *AlarmChange*. The following comparison operators are supported: *=*, *!=*,
*<*, *<=*, *>*, *>=* and *in*; and the following logical operators can be used:
*and* *or* and *not*. The field names are validated against the database
models.

.. note:: The *not* operator has different meaning in Mongo DB and in SQL DB engine.
   If the *not* operator is applied on a non existent metadata field then
   the result depends on the DB engine. For example if
   {"not": {"metadata.nonexistent_field" : "some value"}} filter is used in a query
   the Mongo DB will return every Sample object as *not* operator evaluated true
   for every Sample where the given field does not exists. See more in the Mongod DB doc.
   On the other hand SQL based DB engine will return empty result as the join operation
   on the metadata table will return zero rows as the on clause of the join which
   tries to match on the metadata field name is never fulfilled.

Complex Query supports defining the list of orderby expressions in the form
of [{"field_name": "asc"}, {"field_name2": "desc"}, ...].

The number of the returned items can be bounded using the *limit* option.

The *filter*, *orderby* and *limit* are all optional fields in a query.

.. rest-controller:: aodh.api.controllers.v2.query:QueryAlarmsController
   :webprefix: /v2/query/alarms

.. rest-controller:: aodh.api.controllers.v2.query:QueryAlarmHistoryController
   :webprefix: /v2/query/alarms/history

.. autotype:: aodh.api.controllers.v2.query.ComplexQuery
   :members:

Composite rule Alarm
====================

The *composite* type alarm allows users to specify a composite rule to define
an alarm with multiple triggering conditions, using a combination of *and* and
*or* relations. A composite rule is composed of multiple threshold rules or
gnocchi rules. A sample composite alarm request form is as follows::

   {
       "name": "test_composite",
       "type": "composite",
       "composite_rule": {
           "and": [THRESHOLD_RULE1, THRESHOLD_RULE2, {
               'or': [THRESHOLD_RULE3, GNOCCHI_RULE1,
                      GNOCCHI_RULE2, GNOCCHI_RULE3]
           }]
       }
   }

A sub-rule in composite_rule is same as a threshold_rule in threshold alarm
or a gnocchi_rule in gnocchi alarm. Additionally it has a mandatory *type*
field to specify the rule type, like in the following sample::

   {
       "threshold": 0.8,
       "meter_name": "cpu_util",
       "type": "threshold"
   }