Add a v2 reporting endpoint

See "specs/train/add_v2_reporting_endpoint.rst" for details.

Change-Id: I821a89572610d1d04369571d4d597ed96cc304cd
Story: 2005664
Task: 30957

specs/train/add_v2_reporting_endpoint.rst

@@ -0,0 +1,222 @@
+..
+ This work is licensed under a Creative Commons Attribution 3.0 Unported
+ License.
+
+ http://creativecommons.org/licenses/by/3.0/legalcode
+
+===========================
+Add a v2 reporting endpoint
+===========================
+
+https://storyboard.openstack.org/#!/story/2005664
+
+Problem Description
+===================
+
+Now that the v2 storage has been merged, new features can be implemented on
+top of it. This is a proposal for a v2 endpoint replacing v1's
+``/report/summary``. The endpoint should support filters and grouping on any
+``groupby`` attribute.
+
+Proposed Change
+===============
+
+The proposed endpoint will support pagination, a dict of filters, and a list of
+attributes to group data by.
+
+Example usecases:
+
+* A per-user total for the current month, for the whole cloud:
+
+  Example client usage::
+
+    cloudkitty summary get --groupby user_id
+
+  This would result in the following HTTP request::
+
+    GET /v2/summary?groupby=user_id
+
+* A per-resource total for scope X and user Y for a specific week:
+
+  Example client usage::
+
+    cloudkitty summary get --filter project_id:X --filter user_id:Y --groupby id --begin 2019-05-01T00:00:00 --end 2019-05-07T00:00:00
+
+  This would result in the following HTTP request::
+
+    GET /v2/summary?filter=project_id:X&filter=user_id:Y&groupby=id&begin=2019-05-01T00%3A00%3A00&end=2019-05-07T00%3A00%3A00
+
+Alternatives
+------------
+
+None
+
+Data model impact
+-----------------
+
+There is no direct change to the data model. However, the v2 storage interface
+will have to be updated: no distinction should be made between ``groupby`` and
+``metadata`` filters. Thus, the ``group_filters`` parameter should be removed
+from the prototypes of the ``retrieve`` and ``total`` function.
+
+REST API impact
+---------------
+
+This will add an endpoint on ``/v2/summary`` with support for the ``GET``
+HTTP method.
+
+The method will support the following parameters:
+
+* ``offset``: (optional, defaults to 0) The offset of the first element that
+  should be returned.
+
+* ``limit``: (optional, defaults to 100) The maximal number of results to
+  return.
+
+* ``filter``: (optional) A dict of metadata filters to apply.
+
+* ``groupby``: (optional) A list of attributes to group by.
+
+* ``begin``: (optional, defaults to the first day of the month at midnight)
+  start of the period the request should apply to.
+
+* ``end``: (optional, defaults to the first day of the next month at midnight)
+  end of the period the request should apply to.
+
+A ``GET`` request on this endpoint will return a JSON object of the following
+format:
+
+.. code-block:: yaml
+
+   type: "object"
+   properties:
+     total:
+       type: "integer"
+     columns:
+       type: "array"
+       items:
+         type: "string"
+     results:
+       type: "array"
+       items:
+         oneOf:
+          - type: string
+          - type: string
+            format: datetime
+          - type: integer
+          - type: float
+
+``total`` contains the total number of matching elements (for pagination).
+
+``columns`` contains the list of columns available for each element of
+``results``.
+
+``results`` is a list of same-length arrays sorted in the same way as
+``columns``.
+
+Example response:
+
+.. code-block::
+
+   GET /v2/summary?groupby=user_id
+
+   {
+     "total": 20,
+     "columns": [
+        "begin",
+        "end",
+        "qty",
+        "rate",
+        "user_id"
+     ],
+     "results": [
+        [
+          "2019-05-01T00:00:00Z",
+          "2019-06-01T00:00:00Z",
+          42.21,
+          13.37,
+          "f6b331ad-af19-45b9-a4a3-2d27e8ab76e0"
+        ],
+        [...]
+     ]
+   }
+
+Security impact
+---------------
+
+There is no security impact introduced by this patch.
+
+.. note:: In order to limit access, requests from non-admin users will
+          automatically have a filter on their project added.
+
+Notifications Impact
+--------------------
+
+None
+
+Other end user impact
+---------------------
+
+The client's ``summary get`` method will be updated when using the v2 API in
+order to provide support for pagination, filters and grouping. User experience
+will be improved, as users will have a more precise view of their resource
+usage.
+
+Performance Impact
+------------------
+
+None
+
+Other deployer impact
+---------------------
+
+None
+
+Developer impact
+----------------
+
+None
+
+Implementation
+==============
+
+Assignee(s)
+-----------
+
+Primary assignee:
+  peschk_l
+
+Other contributors:
+  jferrieu
+
+Work Items
+----------
+
+* Update the prototype of the ``retrieve`` and ``total`` methods of the v2
+  storage interface in order to remove the ``group_filters`` parameter.
+
+* Implement the endpoint.
+
+* Add tempest tests for this endpoint.
+
+* Add support for the endpoint to the client.
+
+Dependencies
+============
+
+None
+
+Testing
+=======
+
+Tempest tests for this endpoint will be added.
+
+Documentation Impact
+====================
+
+The endpoint will be added to the API reference.
+
+References
+==========
+
+None