From 57c57e891b88eda5193a0892334b10305d523158 Mon Sep 17 00:00:00 2001
From: Vijendar Komalla <vijendar.komalla@RACKSPACE.COM>
Date: Mon, 16 Jan 2017 14:42:56 -0600
Subject: [PATCH] Magnum stats API documentation

Change-Id: Idf7491ef16aaad744f713bf3c50117f277772e34
Partially-Implements: blueprint magnum-stats-api
---
 api-ref/source/index.rst                   |  1 +
 api-ref/source/parameters.yaml             | 18 +++++
 api-ref/source/samples/stats-get-resp.json |  4 ++
 api-ref/source/stats.inc                   | 82 ++++++++++++++++++++++
 4 files changed, 105 insertions(+)
 create mode 100644 api-ref/source/samples/stats-get-resp.json
 create mode 100644 api-ref/source/stats.inc

diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst
index d30ebd4b8c..2c482ea7c3 100644
--- a/api-ref/source/index.rst
+++ b/api-ref/source/index.rst
@@ -14,3 +14,4 @@
 .. include:: clustertemplates.inc
 .. include:: certificates.inc
 .. include:: mservices.inc
+.. include:: stats.inc
diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index 35ebdb77cc..fe6f8b7fbf 100644
--- a/api-ref/source/parameters.yaml
+++ b/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
diff --git a/api-ref/source/samples/stats-get-resp.json b/api-ref/source/samples/stats-get-resp.json
new file mode 100644
index 0000000000..3fe26ddcde
--- /dev/null
+++ b/api-ref/source/samples/stats-get-resp.json
@@ -0,0 +1,4 @@
+{
+   "clusters": 1,
+   "nodes": 2
+}
diff --git a/api-ref/source/stats.inc b/api-ref/source/stats.inc
new file mode 100644
index 0000000000..d600060486
--- /dev/null
+++ b/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