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.
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": "service", 
            "value": "conductor.tem-devstack-01"
        }, 
        {
            "name": "request_id", 
            "value": "req-4e2d67b8-31a4-48af-bb2f-9df72a353a72"
        }
    ]
}
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>service</name>
      <value>conductor.tem-devstack-01</value>
    </item>
    <item>
      <name>request_id</name>
      <value>req-4e2d67b8-31a4-48af-bb2f-9df72a353a72</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

Panko’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). See api-queries for how to query the API.

type Query

Query filter.

Data samples:

Json
{
    "field": "resource_id", 
    "op": "eq", 
    "type": "string", 
    "value": "bd9431c1-8d69-4ad3-803a-8d4a6b89fd36"
}
XML
<value>
  <field>resource_id</field>
  <op>eq</op>
  <value>bd9431c1-8d69-4ad3-803a-8d4a6b89fd36</value>
  <type>string</type>
</value>
field
Type:unicode

The name of the field to test

op
Type:Enum(lt, le, eq, ne, ge, gt)

The comparison operator. Defaults to ‘eq’.

type
Type:unicode

The data type of value to compare against the stored data

value
Type:unicode

The value to compare against the stored data

Event Query

Event query is similar to simple query, its type EventQuery is actually a subclass of Query, so EventQuery has every attribute Query has. But there are some differences. If a field is one of the following: event_type, message_id, start_timestamp, end_timestamp, then this field will be applied on event, otherwise it will be treated as trait name and applied on trait. 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

Table Of Contents

Previous topic

Web API

Next topic

Installing Panko

Project Source

This Page