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
2017-07-31 17:52:11 +08:00 · 2017-07-31 17:52:11 +08:00 · 5551408fa3
parent 12deae0cd2
commit 5551408fa3
3 changed files with 201 additions and 37 deletions
--- 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
--- 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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~

--- a/api-ref/source/v3/samples/quotas-show-usage-response.json
+++ 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
+        }
+    }
+}