.. 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:: panko.api.controllers.v2.capabilities:CapabilitiesController
   :webprefix: /v2/capabilities

.. autotype:: panko.api.controllers.v2.capabilities.Capabilities
   :members:

Events and Traits
=================

.. rest-controller:: panko.api.controllers.v2.events:EventTypesController
   :webprefix: /v2/event_types

.. rest-controller:: panko.api.controllers.v2.events:TraitsController
   :webprefix: /v2/event_types/(event_type)/traits

.. rest-controller:: panko.api.controllers.v2.events:EventsController
   :webprefix: /v2/events

.. autotype:: panko.api.controllers.v2.events.Event
   :members:

.. autotype:: panko.api.controllers.v2.events.Trait
   :members:

.. autotype:: panko.api.controllers.v2.events.TraitDescription
   :members:

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 :ref:`api-queries` for how to query the API.

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

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 :ref:`api-queries` for how to query the API.

.. autotype:: panko.api.controllers.v2.events.EventQuery
   :members: