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

Aodh's REST API currently supports two types of queries. The Simple
Query functionality provides simple filtering on several fields of the
*Sample* type. Complex Query provides the possibility to specify queries
with logical and comparison operators on the fields of *Sample*.

You may also apply filters based on the values of one or more of the
*resource_metadata* field, which you can identify by using *metadata.<field>*
syntax in either type of query. Note, however, that given the free-form
nature of *resource_metadata* field, there is no practical or consistent way
to validate the query fields under *metadata* domain like it is done for
all other fields.

.. note:: The API call will return HTTP 200 OK status for both of the
   following cases: when a query with *metadata.<field>* does not match its
   value, and when *<field>* itself does not exist in any of the records being
   queried.

Simple Query
++++++++++++

Many of the endpoints above accept a query filter argument, which
should be a list of Query data structures. Whatever the endpoint you
want to apply a filter on, you always filter on the fields of the *Sample*
type (for example, if you apply a filter on a query for statistics,
you won't target *duration_start* field of *Statistics*, but *timestamp*
field of *Sample*).

.. autotype:: aodh.api.controllers.v2.base.Query
   :members:

Complex Query
+++++++++++++

The filter expressions of the Complex Query feature operate on the fields
of *Sample*, *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: