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.

GET /v2/capabilities

Returns a flattened dictionary of API capabilities.

Capabilities supported by the currently configured storage driver.

Return type

Capabilities

Alarms

GET /v2/alarms

Return all alarms, based on the query provided.

Parameters
  • q (list(Query)) – Filter rules for the alarms to be returned.

  • sort (list(str)) – A list of pairs of sort key and sort dir.

  • limit (int) – The maximum number of items to be return.

  • marker (str) – The pagination query marker.

Return type

list(Alarm)

POST /v2/alarms

Create a new alarm.

Parameters
  • data (Alarm) – an alarm within the request body.

Return type

Alarm

GET /v2/alarms/(alarm_id)

Return this alarm.

Return type

Alarm

PUT /v2/alarms/(alarm_id)

Modify this alarm.

Parameters
  • data (Alarm) – an alarm within the request body.

Return type

Alarm

DELETE /v2/alarms/(alarm_id)

Delete this alarm.

GET /v2/alarms/(alarm_id)/history

Assembles the alarm history requested.

Parameters
  • q (list(Query)) – Filter rules for the changes to be described.

  • sort (list(str)) – A list of pairs of sort key and sort dir.

  • limit (int) – The maximum number of items to be return.

  • marker (str) – The pagination query marker.

Return type

list(AlarmChange)

PUT /v2/alarms/(alarm_id)/state

Set the state of this alarm.

Parameters
  • state (Enum(ok, alarm, insufficient data)) – an alarm state within the request body.

Return type

Enum(ok, alarm, insufficient data)

GET /v2/alarms/(alarm_id)/state

Get the state of this alarm.

Return type

Enum(ok, alarm, insufficient data)

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.

POST /v2/query/alarms

Define query for retrieving Alarm data.

Parameters
  • body (ComplexQuery) – Query rules for the alarms to be returned.

Return type

list(Alarm)

POST /v2/query/alarms/history

Define query for retrieving AlarmChange data.

Parameters
  • body (ComplexQuery) – Query rules for the alarm history to be returned.

Return type

list(AlarmChange)

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,
    "meters": [
        "f6857d3f-bde6-441a-aa1d-e98fa4ea543f",
        "ea1491ca-5309-4b5a-9f05-34409c6e8b6c"
    ],
    "type": "gnocchi_resources_threshold"
}