From 5551408fa34721dfa688ddf644aa78e33f0f9bc0 Mon Sep 17 00:00:00 2001
From: TommyLike <tommylikehu@gmail.com>
Date: Mon, 31 Jul 2017 17:52:11 +0800
Subject: [PATCH] Add API document for quota usage.

This patch adds a new API document for quota usage
as it has different response with quota show.

Change-Id: I0a55056f0962743015fec31ce2785aaf482c184d
---
 api-ref/source/v3/parameters.yaml             | 120 +++++++++++++-----
 api-ref/source/v3/quota-sets.inc              |  53 +++++++-
 .../samples/quotas-show-usage-response.json   |  65 ++++++++++
 3 files changed, 201 insertions(+), 37 deletions(-)
 create mode 100644 api-ref/source/v3/samples/quotas-show-usage-response.json

diff --git a/api-ref/source/v3/parameters.yaml b/api-ref/source/v3/parameters.yaml
index bdf65ee89ef..e121a780dbc 100644
--- a/api-ref/source/v3/parameters.yaml
+++ b/api-ref/source/v3/parameters.yaml
@@ -377,7 +377,7 @@ status_query:
   type: boolean
 usage:
   description: |
-    Set to ``usage=true`` to show quota usage.
+    Show project's quota usage information.
     Default is ``false``.
   in: query
   required: false
@@ -405,13 +405,6 @@ alias:
   in: body
   required: true
   type: string
-allocated:
-  description: |
-    Allocated data size. Visible only if you set the
-    ``usage=true`` query parameter.
-  in: body
-  required: false
-  type: integer
 attach_mode:
   description: |
     The attach mode of attachment, read-only ('ro') or
@@ -491,10 +484,18 @@ backup:
   type: object
 backup_gigabytes:
   description: |
-    The size(GB) of backups that are allowed for each project.
+    The size (GB) of backups that are allowed for each project.
   in: body
   required: true
   type: integer
+backup_gigabytes_usage:
+  description: |
+    The size (GB) usage information of backup for this project, including ``in_use``,
+    ``limit``, ``reserved`` and ``allocated`` attributes.
+    Note: ``allocated`` attribute is available only when nested quota is enabled.
+  in: body
+  required: true
+  type: object
 backups:
   description: |
     A list of ``backup`` objects.
@@ -507,6 +508,14 @@ backups_number:
   in: body
   required: true
   type: integer
+backups_number_usage:
+  description: |
+    The backup usage information for this project, including ``in_use``,
+    ``limit``, ``reserved`` and ``allocated`` attributes.
+    Note: ``allocated`` attribute is available only when nested quota is enabled.
+  in: body
+  required: true
+  type: object
 bootable:
   description: |
     Enables or disables the bootable attribute. You
@@ -898,17 +907,34 @@ free_capacity:
   type: string
 gigabytes:
   description: |
-    The size(GB) of volumes and snapshots that are allowed for each project.
+    The size (GB) of volumes and snapshots that are allowed for each project.
   in: body
   required: true
   type: integer
 gigabytes_for_type:
   description: |
-    The size(GB) of volumes and snapshots that are allowed for each project
+    The size (GB) of volumes and snapshots that are allowed for each project
     and the specifed volume type.
   in: body
   required: true
   type: integer
+gigabytes_for_type_usage:
+  description: |
+    The size (GB) usage information of volumes and snapshots for this project
+    and this volume type, including ``in_use``, ``limit``, ``reserved`` and
+    ``allocated`` attributes. Note: ``allocated`` attribute is available only
+    when nested quota is enabled.
+  in: body
+  required: true
+  type: object
+gigabytes_usage:
+  description: |
+    The size (GB) usage information of volumes and snapshots for this project,
+    including ``in_use``, ``limit``, ``reserved`` and ``allocated`` attributes.
+    Note: ``allocated`` attribute is available only when nested quota is enabled.
+  in: body
+  required: true
+  type: object
 group_id_1:
   description: |
     The ID of the group.
@@ -953,6 +979,14 @@ groups_number:
   in: body
   required: true
   type: integer
+groups_number_usage:
+  description: |
+    The group usage information for this project, including ``in_use``,
+    ``limit``, ``reserved`` and ``allocated`` attributes.
+    Note: ``allocated`` attribute is available only when nested quota is enabled.
+  in: body
+  required: true
+  type: object
 guaranteed_until:
   description: |
     The expire time of the message, this message could be
@@ -1066,13 +1100,6 @@ imageRef:
   in: body
   required: false
   type: string
-in_use:
-  description: |
-    The in use data size. Visible only if you set the
-    ``usage=true`` query parameter.
-  in: body
-  required: false
-  type: integer
 incremental:
   description: |
     The backup mode. A valid value is ``true`` for
@@ -1134,13 +1161,6 @@ keys:
   in: body
   required: true
   type: array
-limit_usage:
-  description: |
-    The limit data size. Visible only if you set the
-    ``usage=true`` query parameter.
-  in: body
-  required: false
-  type: integer
 limits:
   description: |
     A list of ``limit`` objects.
@@ -1672,10 +1692,19 @@ os-volume_upload_image:
   type: object
 per_volume_gigabytes:
   description: |
-    The size(GB) of volumes that are allowed for each volume.
+    The size (GB) of volumes that are allowed for each volume.
   in: body
   required: true
   type: integer
+per_volume_gigabytes_usage:
+  description: |
+    The size (GB) usage information for each volume, including ``in_use``,
+    ``limit``, ``reserved`` and ``allocated`` attributes.
+    Note: ``allocated`` attribute is available only when nested quota
+    is enabled and only ``limit`` is meaningful here.
+  in: body
+  required: true
+  type: object
 pool_name:
   description: |
     The name of the storage pool.
@@ -1808,13 +1837,6 @@ request_id:
   in: body
   required: true
   type: string
-reserved:
-  description: |
-    Reserved data size. Visible only if you set the
-    ``usage=true`` query parameter.
-  in: body
-  required: false
-  type: integer
 reserved_percentage:
   description: |
     The percentage of the total capacity that is
@@ -1957,6 +1979,22 @@ snapshots_number_for_type:
   in: body
   required: true
   type: integer
+snapshots_number_for_type_usage:
+  description: |
+    The snapshot usage information for this project and this volume type,
+    including ``in_use``, ``limit``, ``reserved`` and ``allocated`` attributes.
+    Note: ``allocated`` attribute is available only when nested quota is enabled.
+  in: body
+  required: true
+  type: object
+snapshots_number_usage:
+  description: |
+    The snapshot usage information for this project, including ``in_use``,
+    ``limit``, ``reserved`` and ``allocated`` attributes.
+    Note: ``allocated`` attribute is available only when nested quota is enabled.
+  in: body
+  required: true
+  type: object
 source-name:
   description: |
     The resource's name.
@@ -2415,3 +2453,19 @@ volumes_number_for_type:
   in: body
   required: true
   type: integer
+volumes_number_for_type_usage:
+  description: |
+    The volume usage information for this project and this volume type,
+    including ``in_use``, ``limit``, ``reserved`` and ``allocated`` attributes.
+    Note: ``allocated`` attribute is available only when nested quota is enabled.
+  in: body
+  required: true
+  type: object
+volumes_number_usage:
+  description: |
+    The volume usage information for this project, including ``in_use``,
+    ``limit``, ``reserved`` and ``allocated`` attributes.
+    Note: ``allocated`` attribute is available only when nested quota is enabled.
+  in: body
+  required: true
+  type: object
diff --git a/api-ref/source/v3/quota-sets.inc b/api-ref/source/v3/quota-sets.inc
index 700c751149a..ac88b6db79d 100644
--- a/api-ref/source/v3/quota-sets.inc
+++ b/api-ref/source/v3/quota-sets.inc
@@ -47,10 +47,6 @@ Response Parameters
    - gigabytes: gigabytes
    - gigabytes_{volume_type}: gigabytes_for_type
    - backup_gigabytes: backup_gigabytes
-   - in_use: in_use
-   - reserved: reserved
-   - limit: limit_usage
-   - allocated: allocated
 
 Response Example
 ----------------
@@ -58,6 +54,55 @@ Response Example
 .. literalinclude:: ./samples/quotas-show-response.json
    :language: javascript
 
+
+Show quota usage for a project
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  GET /v3/{admin_project_id}/os-quota-sets/{project_id}?{usage}=True
+
+Shows quota usage for a project.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: quotas_project_id
+   - admin_project_id: admin_project_id
+   - usage: usage
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - quota_set: quota_set
+   - id: project_id
+   - volumes: volumes_number_usage
+   - volumes_{volume_type}: volumes_number_for_type_usage
+   - snapshots: snapshots_number_usage
+   - snapshots_{volume_type}: snapshots_number_for_type_usage
+   - backups: backups_number_usage
+   - groups: groups_number_usage
+   - per_volume_gigabytes: per_volume_gigabytes_usage
+   - gigabytes: gigabytes_usage
+   - gigabytes_{volume_type}: gigabytes_for_type_usage
+   - backup_gigabytes: backup_gigabytes_usage
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/quotas-show-usage-response.json
+   :language: javascript
+
+
+
 Update quotas for a project
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/api-ref/source/v3/samples/quotas-show-usage-response.json b/api-ref/source/v3/samples/quotas-show-usage-response.json
new file mode 100644
index 00000000000..44dc8ce9bf4
--- /dev/null
+++ b/api-ref/source/v3/samples/quotas-show-usage-response.json
@@ -0,0 +1,65 @@
+{
+    "quota_set": {
+        "id": "a7090a26bc554d93aa845a4d41808251",
+        "volumes": {
+            "reserved": 0,
+            "allocated": 0,
+            "limit": 10,
+            "in_use": 0
+        },
+        "volumes_lvmdriver-1": {
+            "reserved": 0,
+            "allocated": 0,
+            "limit": -1,
+            "in_use": 0
+        },
+        "snapshots": {
+            "reserved": 0,
+            "allocated": 0,
+            "limit": 10,
+            "in_use": 0
+        },
+        "snapshots_lvmdriver-1": {
+            "reserved": 0,
+            "allocated": 0,
+            "limit": -1,
+            "in_use": 0
+        },
+        "backups": {
+            "reserved": 0,
+            "allocated": 0,
+            "limit": 10,
+            "in_use": 0
+        },
+        "groups": {
+            "reserved": 0,
+            "allocated": 0,
+            "limit": 10,
+            "in_use": 0
+        },
+        "per_volume_gigabytes": {
+            "reserved": 0,
+            "allocated": 0,
+            "limit": -1,
+            "in_use": 0
+        },
+        "gigabytes": {
+            "reserved": 0,
+            "allocated": 0,
+            "limit": 1000,
+            "in_use": 0
+        },
+        "gigabytes_lvmdriver-1": {
+            "reserved": 0,
+            "allocated": 0,
+            "limit": 1000,
+            "in_use": 0
+        },
+        "backup_gigabytes": {
+            "reserved": 0,
+            "allocated": 0,
+            "limit": 1000,
+            "in_use": 0
+        }
+    }
+}