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
type Capabilities

A representation of the API and storage capabilities.

Usually constrained by restrictions imposed by the storage driver.

Data samples:

Json
{
    "api": {
        "events:query:simple": true
    }, 
    "event_storage": {
        "storage:production_ready": true
    }
}
XML
<value>
  <api>
    <item>
      <key>events:query:simple</key>
      <value>true</value>
    </item>
  </api>
  <event_storage>
    <item>
      <key>storage:production_ready</key>
      <value>true</value>
    </item>
  </event_storage>
</value>
api
Type:dict(unicode: bool)

A flattened dictionary of API capabilities

event_storage
Type:dict(unicode: bool)

A flattened dictionary of event storage capabilities

Events and Traits

GET /v2/event_types

Get all event types.

Return type:list(unicode)
GET /v2/event_types/(event_type)

Unused API, will always return 404.

Parameters:
  • event_type (unicode) – A event type
GET /v2/event_types/(event_type)/traits

Return all trait names for an event type.

Parameters:
  • event_type (unicode) – Event type to filter traits by
Return type:

list(TraitDescription)
GET /v2/event_types/(event_type)/traits/(event_type)

Return all instances of a trait for an event type.

Parameters:
  • event_type (unicode) – Event type to filter traits by
  • trait_name (unicode) – Trait to return values for
Return type:

list(Trait)
GET /v2/events

Return all events matching the query filters.

Parameters:
  • q (list(EventQuery)) – Filter arguments for which Events to return
  • limit (int) – Maximum number of samples to be returned.
  • sort (list(str)) – A pair of sort key and sort direction combined with ”:”
  • marker (str) – The pagination query marker, message id of the last item viewed
Return type:

list(Event)
GET /v2/events/(message_id)

Return a single event with the given message id.

Parameters:
  • message_id (unicode) – Message ID of the Event to be returned
Return type:

Event
type Event

A System event.

Data samples:

Json
{
    "event_type": "compute.instance.update", 
    "generated": "2015-01-01T12:00:00", 
    "message_id": "94834db1-8f1b-404d-b2ec-c35901f1b7f0", 
    "raw": {
        "status": {
            "nested": "started"
        }
    }, 
    "traits": [
        {
            "name": "tenant_id", 
            "value": "7f13f2b17917463b9ee21aa92c4b36d6"
        }, 
        {
            "name": "request_id", 
            "value": "req-4e2d67b8-31a4-48af-bb2f-9df72a353a72"
        }, 
        {
            "name": "service", 
            "value": "conductor.tem-devstack-01"
        }
    ]
}
XML
<value>
  <message_id>94834db1-8f1b-404d-b2ec-c35901f1b7f0</message_id>
  <event_type>compute.instance.update</event_type>
  <traits>
    <item>
      <name>tenant_id</name>
      <value>7f13f2b17917463b9ee21aa92c4b36d6</value>
    </item>
    <item>
      <name>request_id</name>
      <value>req-4e2d67b8-31a4-48af-bb2f-9df72a353a72</value>
    </item>
    <item>
      <name>service</name>
      <value>conductor.tem-devstack-01</value>
    </item>
  </traits>
  <generated>2015-01-01T12:00:00</generated>
  <raw>{'status': {'nested': 'started'}}</raw>
</value>
event_type
Type:unicode

The type of the event

generated
Type:datetime

The time the event occurred

message_id
Type:unicode

The message ID for the notification

raw
Type:json

The raw copy of notification

traits
Type:list(Trait)

Event specific properties

type Trait

A Trait associated with an event.

Data samples:

Json
{
    "name": "service", 
    "type": "string", 
    "value": "compute.hostname"
}
XML
<value>
  <name>service</name>
  <value>compute.hostname</value>
  <type>string</type>
</value>
name
Type:unicode

The name of the trait

type
Type:unicode

the type of the trait (string, integer, float or datetime)

value
Type:unicode

the value of the trait

type TraitDescription

A description of a trait, with no associated value.

Data samples:

Json
{
    "name": "service", 
    "type": "string"
}
XML
<value>
  <type>string</type>
  <name>service</name>
</value>
name
Type:unicode

the name of the trait

type
Type:unicode

the data type, defaults to string

Filtering Queries

See api-queries for how to query the API.

type EventQuery

Query arguments for Event Queries.

Data samples:

Json
{
    "field": "event_type", 
    "op": "eq", 
    "type": "string", 
    "value": "compute.instance.create.start"
}
XML
<value>
  <type>string</type>
  <op>eq</op>
  <value>compute.instance.create.start</value>
  <field>event_type</field>
</value>
type
Type:unicode

the type of the trait filter, defaults to string