Magnum stats API documentation

Change-Id: Idf7491ef16aaad744f713bf3c50117f277772e34
Partially-Implements: blueprint magnum-stats-api

api-ref/source/index.rst

@@ -14,3 +14,4 @@
 .. include:: clustertemplates.inc
 .. include:: certificates.inc
 .. include:: mservices.inc
+.. include:: stats.inc

api-ref/source/parameters.yaml

@@ -32,6 +32,12 @@ clustertemplate_ident:
   required: true
   description: |
     The UUID or name of cluster templates in Magnum.
+project_id:
+  type: string
+  in: path
+  required: true
+  description: |
+    Project ID.
 
 # Body params
 api_address:
@@ -106,6 +112,12 @@ cluster_list:
   required: true
   description: |
     The list of all clusters in Magnum.
+clusters:
+  type: integer
+  in: body
+  required: true
+  description: |
+    The number of clusters.
 clustertemplate_id:
   type: UUID
   in: body
@@ -417,6 +429,12 @@ node_count:
   in: body
   required: true
   type: integer
+nodes:
+  description: |
+    The total number of nodes including master nodes.
+  in: body
+  required: true
+  type: integer
 op:
   description: |
     The operation used to modify resource's attributes. Supported operations

api-ref/source/samples/stats-get-resp.json

@@ -0,0 +1,4 @@
+{
+   "clusters": 1,
+   "nodes": 2
+}

api-ref/source/stats.inc

@@ -0,0 +1,82 @@
+.. -*- rst -*-
+
+=================
+ Magnum Stats API
+=================
+
+An admin user can get stats for the given tenant and also overall system stats.
+A non-admin user can get self stats.
+
+Show stats for a tenant
+=======================
+
+.. rest_method:: GET /v1/stats?project_id=<project_id>
+
+Get stats based on project id.
+
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 401
+   - 403
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - project_id: project_id
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+  - clusters: clusters
+  - nodes: nodes
+
+Response Example
+----------------
+
+.. literalinclude:: samples/stats-get-resp.json
+   :language: javascript
+
+Show overall stats
+==================
+
+.. rest_method:: GET /v1/stats
+
+Show overall Magnum system stats.
+If the requester is non-admin user show self stats.
+
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 401
+   - 403
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+  - clusters: clusters
+  - nodes: nodes
+
+Response Example
+----------------
+
+.. literalinclude:: samples/stats-get-resp.json
+   :language: javascript