Add v2 L7 Rule API section

This patch adds the L7 rule section to the v2 API reference.

Change-Id: I43ad86c7cc72b4844247c39f76f30dde349e7a65
Partial-Bug: #1558385

api-ref/source/parameters.yaml

@@ -13,6 +13,12 @@ path-l7policy-id:
   in: path
   required: true
   type: string
+path-l7rule-id:
+  description: |
+    The ID of the L7 rule to query.
+  in: path
+  required: true
+  type: string
 path-listener-id:
   description: |
     The ID of the listener to query.
@@ -150,13 +156,15 @@ bytes_out:
   type: integer
 connection_limit:
   description: |
-    The maximum number of connections permitted for this listener. Default value is -1 which represents infinite connections.
+    The maximum number of connections permitted for this listener. Default
+    value is -1 which represents infinite connections.
   in: body
   required: true
   type: integer
 connection_limit-optional:
   description: |
-    The maximum number of connections permitted for this listener. Default value is -1 which represents infinite connections.
+    The maximum number of connections permitted for this listener. Default
+    value is -1 which represents infinite connections.
   in: body
   required: false
   type: integer
@@ -454,6 +462,81 @@ l7policy-rule-ids:
   in: body
   required: true
   type: array
+l7rule-compare_type:
+  description: |
+    The comparison type for the L7 rule. One of ``CONTAINS``, ``ENDS_WITH``,
+    ``EQUAL_TO``, ``REGEX``, or ``STARTS_WITH``.
+  in: body
+  required: true
+  type: string
+l7rule-compare_type-optional:
+  description: |
+    The comparison type for the L7 rule. One of ``CONTAINS``, ``ENDS_WITH``,
+    ``EQUAL_TO``, ``REGEX``, or ``STARTS_WITH``.
+  in: body
+  required: false
+  type: string
+l7rule-id:
+  description: |
+    The ID of the L7 rule.
+  in: body
+  required: true
+  type: string
+l7rule-invert:
+  description: |
+    When ``true`` the logic of the rule is inverted. For example, with
+    invert ``true``, `equal to` would become `not equal to`.
+  in: body
+  required: true
+  type: boolean
+l7rule-invert-optional:
+  description: |
+    When ``true`` the logic of the rule is inverted. For example, with
+    invert ``true``, `equal to` would become `not equal to`.
+    Default is ``false``.
+  in: body
+  required: false
+  type: boolean
+l7rule-key:
+  description: |
+    The key to use for the comparison. For example, the name of the cookie
+    to evaluate.
+  in: body
+  required: true
+  type: string
+l7rule-key-optional:
+  description: |
+    The key to use for the comparison. For example, the name of the cookie
+    to evaluate.
+  in: body
+  required: false
+  type: string
+l7rule-type:
+  description: |
+    The L7 rule type.  One of ``COOKIE``, ``FILE_TYPE``, ``HEADER``,
+    ``HOST_NAME``, or ``PATH``.
+  in: body
+  required: true
+  type: string
+l7rule-type-optional:
+  description: |
+    The L7 rule type.  One of ``COOKIE``, ``FILE_TYPE``, ``HEADER``,
+    ``HOST_NAME``, or ``PATH``.
+  in: body
+  required: false
+  type: string
+l7rule-value:
+  description: |
+    The value to use for the comparison. For example, the file type to compare.
+  in: body
+  required: true
+  type: string
+l7rule-value-optional:
+  description: |
+    The value to use for the comparison. For example, the file type to compare.
+  in: body
+  required: false
+  type: string
 l7rules-status-object-list:
   description: |
     A list of L7 rule status objects.
@@ -488,7 +571,8 @@ listener-id:
   type: string
 listener-id-pool-optional:
   description: |
-    The ID of the listener for the pool. Either ``listener_id`` or ``loadbalancer_id`` must be specified.
+    The ID of the listener for the pool. Either ``listener_id`` or
+    ``loadbalancer_id`` must be specified.
   in: body
   required: false
   type: string
@@ -530,7 +614,8 @@ loadbalancer-id:
   type: string
 loadbalancer-id-pool-optional:
   description: |
-    The ID of the load balancer for the pool. Either ``listener_id`` or ``loadbalancer_id`` must be specified.
+    The ID of the load balancer for the pool. Either ``listener_id`` or
+    ``loadbalancer_id`` must be specified.
   in: body
   required: false
   type: string
@@ -660,13 +745,15 @@ project_id-optional-deprecated:
   type: string
 protocol:
   description: |
-    The protocol for the resource. One of ``HTTP``, ``HTTPS``, ``TCP``, or ``TERMINATED_HTTPS``.
+    The protocol for the resource. One of ``HTTP``, ``HTTPS``, ``TCP``, or
+    ``TERMINATED_HTTPS``.
   in: body
   required: true
   type: integer
 protocol-pools:
   description: |
-    The protocol for the resource. One of ``HTTP``, ``HTTPS``, ``PROXY``, or ``TCP``.
+    The protocol for the resource. One of ``HTTP``, ``HTTPS``, ``PROXY``, or
+    ``TCP``.
   in: body
   required: true
   type: string

api-ref/source/v2/examples/l7policy-create-response.json

@@ -1,5 +1,5 @@
 {
-    "l7policies": [
+    "l7policy": [
         {
             "listener_id": "023f2e34-7806-443b-bfae-16c324569a3d",
             "description": "Redirect requests to example.com",

api-ref/source/v2/examples/l7policy-show-response.json

@@ -1,5 +1,5 @@
 {
-    "l7policies":
+    "l7policy":
         {
             "listener_id": "023f2e34-7806-443b-bfae-16c324569a3d",
             "description": "Redirect requests to example.com",

api-ref/source/v2/examples/l7policy-update-response.json

@@ -1,5 +1,5 @@
 {
-    "l7policies":
+    "l7policy":
         {
             "listener_id": "023f2e34-7806-443b-bfae-16c324569a3d",
             "description": "Redirect requests to example.com",

api-ref/source/v2/examples/l7rule-create-curl

@@ -0,0 +1 @@
+curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <token>" -d '{"rule":{"compare_type":"REGEX","invert":false,"type":"PATH","value":"/images*","admin_state_up":true}}' http://198.51.100.10:9876/v2.0/lbaas/l7policies/8a1412f0-4c32-4257-8b07-af4770b604fd/rules

api-ref/source/v2/examples/l7rule-create-request.json

@@ -0,0 +1,9 @@
+{
+    "rule": {
+        "compare_type": "REGEX",
+        "invert": false,
+        "type": "PATH",
+        "value": "/images*",
+        "admin_state_up": true
+    }
+}

api-ref/source/v2/examples/l7rule-create-response.json

@@ -0,0 +1,17 @@
+{
+    "rule":
+        {
+            "created_at": "2017-06-27T15:52:27",
+            "compare_type": "REGEX",
+            "provisioning_status": "PENDING_CREATE",
+            "invert": false,
+            "admin_state_up": true,
+            "updated_at": "2017-06-27T15:52:28",
+            "value": "/images*",
+            "key": null,
+            "project_id": "e3cd678b11784734bc366148aa37580e",
+            "type": "PATH",
+            "id": "16621dbb-a736-4888-a57a-3ecd53df784c",
+            "operating_status": "OFFLINE"
+        }
+}

api-ref/source/v2/examples/l7rule-delete-curl

@@ -0,0 +1 @@
+curl -X DELETE -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2.0/lbaas/l7policies/8a1412f0-4c32-4257-8b07-af4770b604fd/rules/16621dbb-a736-4888-a57a-3ecd53df784c

api-ref/source/v2/examples/l7rule-show-curl

@@ -0,0 +1 @@
+curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2.0/lbaas/l7policies/8a1412f0-4c32-4257-8b07-af4770b604fd/rules/16621dbb-a736-4888-a57a-3ecd53df784c

api-ref/source/v2/examples/l7rule-show-response.json

@@ -0,0 +1,17 @@
+{
+    "rule":
+        {
+            "created_at": "2017-06-27T15:52:27",
+            "compare_type": "REGEX",
+            "provisioning_status": "ACTIVE",
+            "invert": false,
+            "admin_state_up": true,
+            "updated_at": "2017-06-27T15:52:28",
+            "value": "/images*",
+            "key": null,
+            "project_id": "e3cd678b11784734bc366148aa37580e",
+            "type": "PATH",
+            "id": "16621dbb-a736-4888-a57a-3ecd53df784c",
+            "operating_status": "ONLINE"
+        }
+}

api-ref/source/v2/examples/l7rule-update-curl

@@ -0,0 +1 @@
+curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: <token>" -d '{"rule":{"compare_type":"REGEX","invert":true,"type":"PATH","value":"/images/special*","admin_state_up":true}}' http://198.51.100.10:9876/v2.0/lbaas/l7policies/8a1412f0-4c32-4257-8b07-af4770b604fd/rules/16621dbb-a736-4888-a57a-3ecd53df784c

api-ref/source/v2/examples/l7rule-update-request.json

@@ -0,0 +1,9 @@
+{
+    "rule": {
+        "compare_type": "REGEX",
+        "invert": true,
+        "type": "PATH",
+        "value": "/images/special*",
+        "admin_state_up": true
+    }
+}

api-ref/source/v2/examples/l7rule-update-response.json

@@ -0,0 +1,17 @@
+{
+    "rule":
+        {
+            "created_at": "2017-06-27T15:52:27",
+            "compare_type": "REGEX",
+            "provisioning_status": "PENDING_UPDATE",
+            "invert": true,
+            "admin_state_up": true,
+            "updated_at": "2017-06-27T15:58:28",
+            "value": "/images/special*",
+            "key": null,
+            "project_id": "e3cd678b11784734bc366148aa37580e",
+            "type": "PATH",
+            "id": "16621dbb-a736-4888-a57a-3ecd53df784c",
+            "operating_status": "ONLINE"
+        }
+}

api-ref/source/v2/examples/l7rules-list-curl

@@ -0,0 +1 @@
+curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2.0/lbaas/l7policies/8a1412f0-4c32-4257-8b07-af4770b604fd/rules

api-ref/source/v2/examples/l7rules-list-response.json

@@ -0,0 +1,18 @@
+{
+    "rules": [
+        {
+            "created_at": "2017-06-27T15:52:27",
+            "compare_type": "REGEX",
+            "provisioning_status": "ACTIVE",
+            "invert": false,
+            "admin_state_up": true,
+            "updated_at": "2017-06-27T15:52:28",
+            "value": "/images*",
+            "key": null,
+            "project_id": "e3cd678b11784734bc366148aa37580e",
+            "type": "PATH",
+            "id": "16621dbb-a736-4888-a57a-3ecd53df784c",
+            "operating_status": "ONLINE"
+        }
+    ]
+}

api-ref/source/v2/index.rst

@@ -40,3 +40,8 @@ Health Monitor
 L7 Policies
 -----------
 .. include:: l7policy.inc
+
+--------
+L7 Rules
+--------
+.. include:: l7rule.inc

api-ref/source/v2/l7rule.inc

@@ -0,0 +1,348 @@
+.. -*- rst -*-
+
+List L7 Rules
+=============
+
+.. rest_method:: GET /v2.0/lbaas/l7policies/{l7policy_id}/rules
+
+Lists all L7 rules for the project.
+
+Use the ``fields`` query parameter to control which fields are
+returned in the response body. Additionally, you can filter results
+by using query string parameters. For information, see :ref:`filtering`.
+
+Administrative users can specify a project ID that is different than their own
+to list L7 policies for other projects.
+
+The list might be empty.
+
+.. rest_status_code:: success ../http-status.yaml
+
+   - 200
+
+.. rest_status_code:: error ../http-status.yaml
+
+   - 400
+   - 401
+   - 500
+
+Request
+-------
+
+.. rest_parameters:: ../parameters.yaml
+
+   - fields: fields
+   - l7policy_id: path-l7policy-id
+   - project_id: project_id_query
+
+Curl Example
+------------
+
+.. literalinclude:: examples/l7rules-list-curl
+   :language: bash
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: ../parameters.yaml
+
+   - admin_state_up: admin_state_up
+   - compare_type: l7rule-compare_type
+   - created_at: created_at
+   - id: l7rule-id
+   - invert: l7rule-invert
+   - key: l7rule-key
+   - operating_status: operating_status
+   - project_id: project_id
+   - provisioning_status: provisioning_status
+   - type: l7rule-type
+   - updated_at: updated_at
+   - value: l7rule-value
+
+Response Example
+----------------
+
+.. literalinclude:: examples/l7rules-list-response.json
+   :language: javascript
+
+Create an L7 Rule
+=================
+
+.. rest_method:: POST /v2.0/lbaas/l7policies/{l7policy_id}/rules
+
+Creates a L7 rule.
+
+This operation provisions a new L7 rule by using the
+configuration that you define in the request object. After the API
+validates the request and starts the provisioning process, the API
+returns a response object that contains a unique ID and the status
+of provisioning the L7 rule.
+
+In the response, the L7 rule :ref:`provisioning status<prov_status>` is
+``ACTIVE``, ``PENDING_CREATE``, or ``ERROR``.
+
+If the status is ``PENDING_CREATE``, issue GET
+``/v2.0/lbaas/l7policies/{l7policy_id}/rules/{l7rule_id}`` to view the
+progress of the provisioning operation. When the L7 rule status changes
+to ``ACTIVE``, the L7 rule is successfully provisioned and
+is ready for further configuration.
+
+If the API cannot fulfill the request due to insufficient data or
+data that is not valid, the service returns the HTTP ``Bad Request
+(400)`` response code with information about the failure in the
+response body. Validation errors require that you correct the error
+and submit the request again.
+
+All the rules associated with a given policy are logically ANDed together. A
+request must match all the policy’s rules to match the policy.
+
+If you need to express a logical OR operation between rules, then do this by
+creating multiple policies with the same action.
+
+.. rest_status_code:: success ../http-status.yaml
+
+   - 201
+
+.. rest_status_code:: error ../http-status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+   - 409
+   - 500
+   - 503
+
+Request
+-------
+
+.. rest_parameters:: ../parameters.yaml
+
+   - admin_state_up: admin_state_up-default-optional
+   - compare_type: l7rule-compare_type
+   - invert: l7rule-invert-optional
+   - key: l7rule-key-optional
+   - l7policy_id: path-l7policy-id
+   - project_id: project_id-optional
+   - type: l7rule-type
+   - value: l7rule-value
+
+Request Example
+----------------
+
+.. literalinclude:: examples/l7rule-create-request.json
+   :language: javascript
+
+Curl Example
+------------
+
+.. literalinclude:: examples/l7rule-create-curl
+   :language: bash
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: ../parameters.yaml
+
+   - admin_state_up: admin_state_up
+   - compare_type: l7rule-compare_type
+   - created_at: created_at
+   - id: l7rule-id
+   - invert: l7rule-invert
+   - key: l7rule-key
+   - operating_status: operating_status
+   - project_id: project_id
+   - provisioning_status: provisioning_status
+   - type: l7rule-type
+   - updated_at: updated_at
+   - value: l7rule-value
+
+Response Example
+----------------
+
+.. literalinclude:: examples/l7rule-create-response.json
+   :language: javascript
+
+Show L7 Rule details
+==========================
+
+.. rest_method:: GET /v2.0/lbaas/l7policies/{l7policy_id}/rules/{l7rule_id}
+
+Shows the details of a L7 rule.
+
+If you are not an administrative user and the L7 rule object does not
+belong to your project, the service returns the HTTP ``Forbidden (403)``
+response code.
+
+This operation does not require a request body.
+
+.. rest_status_code:: success ../http-status.yaml
+
+   - 200
+
+.. rest_status_code:: error ../http-status.yaml
+
+   - 401
+   - 403
+   - 404
+   - 500
+
+Request
+-------
+
+.. rest_parameters:: ../parameters.yaml
+
+   - fields: fields
+   - l7policy_id: path-l7policy-id
+   - l7rule_id: path-l7rule-id
+
+Curl Example
+------------
+
+.. literalinclude:: examples/l7rule-show-curl
+   :language: bash
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: ../parameters.yaml
+
+   - admin_state_up: admin_state_up
+   - compare_type: l7rule-compare_type
+   - created_at: created_at
+   - id: l7rule-id
+   - invert: l7rule-invert
+   - key: l7rule-key
+   - operating_status: operating_status
+   - project_id: project_id
+   - provisioning_status: provisioning_status
+   - type: l7rule-type
+   - updated_at: updated_at
+   - value: l7rule-value
+
+Response Example
+----------------
+
+.. literalinclude:: examples/l7rule-show-response.json
+   :language: javascript
+
+Update a L7 Rule
+================
+
+.. rest_method:: PUT /v2.0/lbaas/l7policies/{l7policy_id}/rules/{l7rule_id}
+
+Updates a L7 rule.
+
+If the request is valid, the service returns the ``Accepted (202)``
+response code. To confirm the update, check that the L7 rule
+provisioning status is ``ACTIVE``. If the status is
+``PENDING_UPDATE``, use a GET operation to poll the L7 rule
+object for changes.
+
+This operation returns the updated L7 rule object with the
+``ACTIVE``, ``PENDING_UPDATE``, or ``ERROR`` provisioning status.
+
+.. rest_status_code:: success ../http-status.yaml
+
+   - 202
+
+.. rest_status_code:: error ../http-status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+   - 409
+   - 500
+
+Request
+-------
+
+.. rest_parameters:: ../parameters.yaml
+
+   - admin_state_up: admin_state_up-default-optional
+   - compare_type: l7rule-compare_type-optional
+   - invert: l7rule-invert-optional
+   - key: l7rule-key-optional
+   - l7policy_id: path-l7policy-id
+   - l7rule_id: path-l7rule-id
+   - type: l7rule-type-optional
+   - value: l7rule-value-optional
+
+Request Example
+---------------
+
+.. literalinclude:: examples/l7rule-update-request.json
+   :language: javascript
+
+Curl Example
+------------
+
+.. literalinclude:: examples/l7rule-update-curl
+   :language: bash
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: ../parameters.yaml
+
+   - admin_state_up: admin_state_up
+   - compare_type: l7rule-compare_type
+   - created_at: created_at
+   - id: l7rule-id
+   - invert: l7rule-invert
+   - key: l7rule-key
+   - operating_status: operating_status
+   - project_id: project_id
+   - provisioning_status: provisioning_status
+   - type: l7rule-type
+   - updated_at: updated_at
+   - value: l7rule-value
+
+Response Example
+----------------
+
+.. literalinclude:: examples/l7rule-update-response.json
+   :language: javascript
+
+Remove a L7 Rule
+================
+
+.. rest_method:: DELETE /v2.0/lbaas/l7policies/{l7policy_id}/rules/{l7rule_id}
+
+Removes a L7 rule and its associated configuration from the project.
+
+The API immediately purges any and all configuration data, depending on the
+configuration settings. You cannot recover it.
+
+.. rest_status_code:: success ../http-status.yaml
+
+   - 204
+
+.. rest_status_code:: error ../http-status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+   - 409
+   - 500
+
+Request
+-------
+
+.. rest_parameters:: ../parameters.yaml
+
+   - l7policy_id: path-l7policy-id
+   - l7rule_id: path-l7rule-id
+
+Curl Example
+------------
+
+.. literalinclude:: examples/l7rule-delete-curl
+   :language: bash
+
+Response
+--------
+
+There is no body content for the response of a successful DELETE request.