| 1 |
================ |
| 2 |
Summary endpoint |
| 3 |
================ |
| 4 |
|
| 5 |
Get a rating summary |
| 6 |
==================== |
| 7 |
|
| 8 |
Get a rating summary for one or several tenants. |
| 9 |
|
| 10 |
.. rest_method:: GET /v2/summary |
| 11 |
|
| 12 |
.. rest_parameters:: summary/summary_parameters.yml |
| 13 |
|
| 14 |
- limit: limit |
| 15 |
- offset: offset |
| 16 |
- begin: begin |
| 17 |
- end: end |
| 18 |
- groupby: groupby |
| 19 |
- filters: filters |
| 20 |
- custom_fields: custom_fields |
| 21 |
- response_format: response_format |
| 22 |
|
| 23 |
Status codes |
| 24 |
------------ |
| 25 |
|
| 26 |
.. rest_status_code:: success http_status.yml |
| 27 |
|
| 28 |
- 200 |
| 29 |
|
| 30 |
.. rest_status_code:: error http_status.yml |
| 31 |
|
| 32 |
- 400 |
| 33 |
- 403 |
| 34 |
- 405 |
| 35 |
|
| 36 |
Response |
| 37 |
-------- |
| 38 |
|
| 39 |
The response has the following default format (response_format='table'): |
| 40 |
|
| 41 |
.. code-block:: javascript |
| 42 |
|
| 43 |
{ |
| 44 |
"columns": [ |
| 45 |
"begin", |
| 46 |
"end", |
| 47 |
"qty", |
| 48 |
"rate", |
| 49 |
"group1", |
| 50 |
"group2", |
| 51 |
], |
| 52 |
"results": [ |
| 53 |
[ |
| 54 |
"2019-06-01T00:00:00Z", |
| 55 |
"2019-07-01T00:00:00Z", |
| 56 |
2590.421676635742, |
| 57 |
1295.210838317871, |
| 58 |
"group1", |
| 59 |
"group2", |
| 60 |
] |
| 61 |
], |
| 62 |
"total": 4 |
| 63 |
} |
| 64 |
|
| 65 |
``total`` is the total amount of found elements. ``columns`` contains the name of |
| 66 |
the columns for each element of ``results``. The columns are the four mandatory ones |
| 67 |
(``begin``, ``end``, ``qty``, ``rate``) along with each attribute the result is |
| 68 |
grouped by. |
| 69 |
|
| 70 |
``format`` is the response format. It can be "table" or "object". The default |
| 71 |
response structure is "table", which is presented above. The object structure |
| 72 |
uses the following pattern. |
| 73 |
|
| 74 |
.. code-block:: javascript |
| 75 |
|
| 76 |
{ |
| 77 |
"results": [ |
| 78 |
{"begin": "2019-06-01T00:00:00Z", |
| 79 |
"end": "2019-07-01T00:00:00Z", |
| 80 |
"qty": 2590.421676635742, |
| 81 |
"rate": 1295.210838317871, |
| 82 |
"group1": "group1", |
| 83 |
"group2": "group2", |
| 84 |
}, |
| 85 |
], |
| 86 |
"total": 4 |
| 87 |
} |
| 88 |
|
| 89 |
.. note:: It is also possible to group data by time, in order to obtain timeseries. |
| 90 |
In order to do this, group by ``time``. No extra column will be added, |
| 91 |
but you'll get one entry per collect period in the queried timeframe. |
| 92 |
See examples below. |
| 93 |
|
| 94 |
.. rest_parameters:: summary/summary_parameters.yml |
| 95 |
|
| 96 |
- begin: begin_resp |
| 97 |
- end: end_resp |
| 98 |
- qty: qty_resp |
| 99 |
- rate: rate_resp |
| 100 |
|
| 101 |
Response Example |
| 102 |
---------------- |
| 103 |
|
| 104 |
Grouping by time and project_id: |
| 105 |
|
| 106 |
.. code-block:: shell |
| 107 |
|
| 108 |
curl "http://cloudkitty-api:8889/v2/summary?groupby=time&groupby=project_id&limit=3" |
| 109 |
|
| 110 |
.. literalinclude:: ./api_samples/summary/summary_get_groupby_time.json |
| 111 |
:language: javascript |
| 112 |
|
| 113 |
.. code-block:: shell |
| 114 |
|
| 115 |
curl "http://cloudkitty-api:8889/v2/summary?filters=project_id%3Afe9c35372db6420089883805b37a34af&groupby=type&groupby=project_id" |
| 116 |
|
| 117 |
.. literalinclude:: ./api_samples/summary/summary_get.json |
| 118 |
:language: javascript |