From 1017027970a013bc519f7fa3e8f64b457c766f11 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C5=82awek=20Kap=C5=82o=C5=84ski?= <slawek@kaplonski.pl>
Date: Fri, 14 Jul 2017 05:37:46 +0000
Subject: [PATCH] Add description of API call to get QoS rule type details

There is new API call available in Neutron QoS to get details
about supported QoS rule type.
This patch adds description of this call in api-ref.

Change-Id: Iec8eebcccf3addbbd35294a65137e586aedadc11
Closes-Bug: 1703976
---
 api-ref/source/v2/parameters.yaml             | 26 ++++++++
 api-ref/source/v2/qos.inc                     | 43 ++++++++++++-
 .../qos/rule_type-details-response.json       | 63 +++++++++++++++++++
 3 files changed, 131 insertions(+), 1 deletion(-)
 create mode 100644 api-ref/source/v2/samples/qos/rule_type-details-response.json

diff --git a/api-ref/source/v2/parameters.yaml b/api-ref/source/v2/parameters.yaml
index c13339a0b..51d2258ec 100644
--- a/api-ref/source/v2/parameters.yaml
+++ b/api-ref/source/v2/parameters.yaml
@@ -211,6 +211,14 @@ qos-rule_id:
   in: path
   required: true
   type: string
+qos-rule_type:
+  description: |
+    The name of the QoS rule type. It should be one of the types
+    returned by the List QoS rule types API, for example
+    ``bandwidth_limit`` or ``dscp_marking``.
+  in: path
+  required: true
+  type: string
 rbac_policy_id-path:
   description: |
     The ID of the RBAC policy.
@@ -4377,6 +4385,24 @@ psk:
   in: body
   required: true
   type: string
+qos-backend-drivers:
+  description: |
+      List of loaded QoS drivers with supported
+      rule type parameters with possible values for each.
+      Each driver is represented by a dict with the keys
+      ``name`` and ``supported_parameters``.
+      Field ``name`` contains the name of a backend driver.
+      Field ``supported_parameters`` contains a list of dicts with
+      ``parameter_name``, ``parameter_type`` and ``parameter_values``
+      fields.
+      The valid values for ``parameter_type`` are ``choices`` or ``range``.
+      If ``parameter_type`` is ``choices`` then ``parameter_values``
+      contains a list of acceptable values, otherwise it contains
+      a dict with keys of ``start`` and ``end`` which define the range
+      of acceptable values.
+  in: body
+  required: true
+  type: list
 qos-rule-direction:
   description: |
     The direction of the traffic to which the QoS
diff --git a/api-ref/source/v2/qos.inc b/api-ref/source/v2/qos.inc
index f2c315e2b..6bdce7e04 100644
--- a/api-ref/source/v2/qos.inc
+++ b/api-ref/source/v2/qos.inc
@@ -4,7 +4,7 @@
 QoS rule types
 ==============
 
-List QoS rule types available in current deployment.
+Lists and shows information for QoS rule types available in current deployment.
 
 List QoS rule types
 ===================
@@ -31,6 +31,47 @@ Response Example
 .. literalinclude:: samples/qos/rule_types-list-response.json
    :language: javascript
 
+Show QoS rule type details
+==========================
+
+.. rest_method:: GET /v2.0/qos/rule-types/{rule_type}
+
+Shows details for an available QoS rule type.
+
+To determine if this API call is available, a user can check whether
+the ``qos-rule-type-details`` extension API is available.
+
+You can control which response parameters are returned by using the
+fields query parameter. For information, see `Filtering and column
+selection <http://specs.openstack.org/openstack/neutron-
+specs/specs/api/networking_general_api_information.html#filtering-
+and-column-selection>`__.
+
+Normal response codes: 200
+
+Error response codes: 401, 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - rule_type: qos-rule_type
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - type: qos-rule-type
+   - drivers: qos-backend-drivers
+
+Response Example
+----------------
+
+.. literalinclude:: samples/qos/rule_type-details-response.json
+   :language: javascript
+
 ==================
 QoS policies (qos)
 ==================
diff --git a/api-ref/source/v2/samples/qos/rule_type-details-response.json b/api-ref/source/v2/samples/qos/rule_type-details-response.json
new file mode 100644
index 000000000..72b927689
--- /dev/null
+++ b/api-ref/source/v2/samples/qos/rule_type-details-response.json
@@ -0,0 +1,63 @@
+{
+    "drivers": [
+        {
+            "name": "openvswitch",
+            "supported_parameters": [
+                {
+                    "parameter_name": "max_kbps",
+                    "parameter_type": "range",
+                    "parameter_values": {
+                        "end": 2147483647,
+                        "start": 0
+                    }
+                },
+                {
+                    "parameter_name": "direction",
+                    "parameter_type": "choices",
+                    "parameter_values": [
+                        "ingress",
+                        "egress"
+                    ]
+                },
+                {
+                    "parameter_name": "max_burst_kbps",
+                    "parameter_type": "range",
+                    "parameter_values": {
+                        "end": 2147483647,
+                        "start": 0
+                    }
+                }
+            ]
+        },
+        {
+            "name": "linuxbridge",
+            "supported_parameters": [
+                {
+                    "parameter_name": "max_kbps",
+                    "parameter_type": "range",
+                    "parameter_values": {
+                        "end": 2147483647,
+                        "start": 0
+                    }
+                },
+                {
+                    "parameter_name": "direction",
+                    "parameter_type": "choices",
+                    "parameter_values": [
+                        "ingress",
+                        "egress"
+                    ]
+                },
+                {
+                    "parameter_name": "max_burst_kbps",
+                    "parameter_type": "range",
+                    "parameter_values": {
+                        "end": 2147483647,
+                        "start": 0
+                    }
+                }
+            ]
+        }
+    ],
+    "type": "bandwidth_limit"
+}