Debian Codegraph @

api-ref/source/v2/summary/summary.inc

raw
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