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

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