Add v2 L7 Policy API section

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

This patch also updates the child object create error code lists to
include 409 as a possible error code.

Change-Id: I6cb469c65832af3440c18dc71c7786a8fbf9bd2b
Partial-Bug: #1558385

api-ref/source/parameters.yaml

@@ -7,6 +7,12 @@ path-healthmonitor-id:
   in: path
   required: true
   type: string
+path-l7policy-id:
+  description: |
+    The ID of the L7 policy to query.
+  in: path
+  required: true
+  type: string
 path-listener-id:
   description: |
     The ID of the listener to query.
@@ -376,12 +382,78 @@ l7policies-status-object-list:
   in: body
   required: true
   type: array
+l7policy-action:
+  description: |
+    The L7 policy action.  One of ``REDIRECT_TO_POOL``, ``REDIRECT_TO_URL``,
+    or ``REJECT``.
+  in: body
+  required: true
+  type: string
+l7policy-action-optional:
+  description: |
+    The L7 policy action.  One of ``REDIRECT_TO_POOL``, ``REDIRECT_TO_URL``,
+    or ``REJECT``.
+  in: body
+  required: false
+  type: string
+l7policy-id:
+  description: |
+    The ID of the L7 policy.
+  in: body
+  required: true
+  type: string
 l7policy-ids:
   description: |
     A list of L7 policy IDs.
   in: body
   required: true
   type: array
+l7policy-position:
+  description: |
+    The position of this policy on the listener. Positions start at 1.
+  in: body
+  required: true
+  type: integer
+l7policy-position-optional:
+  description: |
+    The position of this policy on the listener. Positions start at 1.
+  in: body
+  required: false
+  type: integer
+l7policy-redirect-pool_id:
+  description: |
+    Requests matching this policy will be redirected to the pool with this ID.
+    Only valid if ``action`` is ``REDIRECT_TO_POOL``.
+  in: body
+  required: true
+  type: string
+l7policy-redirect-pool_id-optional:
+  description: |
+    Requests matching this policy will be redirected to the pool with this ID.
+    Only valid if ``action`` is ``REDIRECT_TO_POOL``.
+  in: body
+  required: false
+  type: string
+l7policy-redirect-url:
+  description: |
+    Requests matching this policy will be redirected to this URL.
+    Only valid if ``action`` is ``REDIRECT_TO_URL``.
+  in: body
+  required: true
+  type: string
+l7policy-redirect-url-optional:
+  description: |
+    Requests matching this policy will be redirected to this URL.
+    Only valid if ``action`` is ``REDIRECT_TO_URL``.
+  in: body
+  required: false
+  type: string
+l7policy-rule-ids:
+  description: |
+    List of associated L7 rule IDs.
+  in: body
+  required: true
+  type: array
 l7rules-status-object-list:
   description: |
     A list of L7 rule status objects.

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

@@ -0,0 +1 @@
+curl -X GET -H "X-Auth-Token: <token>" http://198.51.100.10:9876/v2.0/lbaas/l7policies?project_id=e3cd678b11784734bc366148aa37580e

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

@@ -0,0 +1,25 @@
+{
+    "l7policies": [
+        {
+            "listener_id": "023f2e34-7806-443b-bfae-16c324569a3d",
+            "description": "Redirect requests to example.com",
+            "admin_state_up": true,
+            "rules": [
+                {
+                    "id": "efd6a3f8-73bf-47f0-8ae6-503ebda57372"
+                }
+            ],
+            "created_at": "2017-06-24T23:25:14",
+            "provisioning_status": "ACTIVE",
+            "updated_at": "2017-06-24T23:30:05",
+            "redirect_pool_id": null,
+            "redirect_url": "http://www.example.com",
+            "action": "REDIRECT_TO_URL",
+            "position": 1,
+            "project_id": "e3cd678b11784734bc366148aa37580e",
+            "id": "8a1412f0-4c32-4257-8b07-af4770b604fd",
+            "operating_status": "ONLINE",
+            "name": "redirect-example.com"
+        }
+    ]
+}

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

@@ -0,0 +1 @@
+curl -X POST -H "Content-Type: application/json" -H "X-Auth-Token: <token>" -d '{"l7policy":{"description":"Redirect requests to example.com","admin_state_up":true,"listener_id":"023f2e34-7806-443b-bfae-16c324569a3d","redirect_url":"http://www.example.com","name":"redirect-example.com","action":"REDIRECT_TO_URL","position":1}}' http://198.51.100.10:9876/v2.0/lbaas/l7policies

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

@@ -0,0 +1,11 @@
+{
+    "l7policy": {
+        "description": "Redirect requests to example.com",
+        "admin_state_up": true,
+        "listener_id": "023f2e34-7806-443b-bfae-16c324569a3d",
+        "redirect_url": "http://www.example.com",
+        "name": "redirect-example.com",
+        "action": "REDIRECT_TO_URL",
+        "position": 1
+    }
+}

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

@@ -0,0 +1,25 @@
+{
+    "l7policies": [
+        {
+            "listener_id": "023f2e34-7806-443b-bfae-16c324569a3d",
+            "description": "Redirect requests to example.com",
+            "admin_state_up": true,
+            "rules": [
+                {
+                    "id": "efd6a3f8-73bf-47f0-8ae6-503ebda57372"
+                }
+            ],
+            "created_at": "2017-06-24T23:25:14",
+            "provisioning_status": "PENDING_CREATE",
+            "updated_at": "2017-06-24T23:30:05",
+            "redirect_pool_id": null,
+            "redirect_url": "http://www.example.com",
+            "action": "REDIRECT_TO_URL",
+            "position": 1,
+            "project_id": "e3cd678b11784734bc366148aa37580e",
+            "id": "8a1412f0-4c32-4257-8b07-af4770b604fd",
+            "operating_status": "OFFLINE",
+            "name": "redirect-example.com"
+        }
+    ]
+}

api-ref/source/v2/examples/l7policy-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

api-ref/source/v2/examples/l7policy-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

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

@@ -0,0 +1,24 @@
+{
+    "l7policies":
+        {
+            "listener_id": "023f2e34-7806-443b-bfae-16c324569a3d",
+            "description": "Redirect requests to example.com",
+            "admin_state_up": true,
+            "rules": [
+                {
+                    "id": "efd6a3f8-73bf-47f0-8ae6-503ebda57372"
+                }
+            ],
+            "created_at": "2017-06-24T23:25:14",
+            "provisioning_status": "ACTIVE",
+            "updated_at": "2017-06-24T23:30:05",
+            "redirect_pool_id": null,
+            "redirect_url": "http://www.example.com",
+            "action": "REDIRECT_TO_URL",
+            "position": 1,
+            "project_id": "e3cd678b11784734bc366148aa37580e",
+            "id": "8a1412f0-4c32-4257-8b07-af4770b604fd",
+            "operating_status": "ONLINE",
+            "name": "redirect-example.com"
+        }
+}

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

@@ -0,0 +1 @@
+curl -X PUT -H "Content-Type: application/json" -H "X-Auth-Token: <token>" -d '{"l7policy":{"description":"Redirect requests to images.example.com","admin_state_up":true,"redirect_url":"http://images.example.com","name":"redirect-images.example.com","action":"REDIRECT_TO_URL","position":1}}' http://198.51.100.10:9876/v2.0/lbaas/l7policies/8a1412f0-4c32-4257-8b07-af4770b604fd

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

@@ -0,0 +1,10 @@
+{
+    "l7policy": {
+        "description": "Redirect requests to images.example.com",
+        "admin_state_up": true,
+        "redirect_url": "http://images.example.com",
+        "name": "redirect-images.example.com",
+        "action": "REDIRECT_TO_URL",
+        "position": 1
+    }
+}

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

@@ -0,0 +1,24 @@
+{
+    "l7policies":
+        {
+            "listener_id": "023f2e34-7806-443b-bfae-16c324569a3d",
+            "description": "Redirect requests to example.com",
+            "admin_state_up": true,
+            "rules": [
+                {
+                    "id": "efd6a3f8-73bf-47f0-8ae6-503ebda57372"
+                }
+            ],
+            "created_at": "2017-06-24T23:25:14",
+            "provisioning_status": "PENDING_UPDATE",
+            "updated_at": "2017-06-24T23:30:05",
+            "redirect_pool_id": null,
+            "redirect_url": "http://www.example.com",
+            "action": "REDIRECT_TO_URL",
+            "position": 1,
+            "project_id": "e3cd678b11784734bc366148aa37580e",
+            "id": "8a1412f0-4c32-4257-8b07-af4770b604fd",
+            "operating_status": "ONLINE",
+            "name": "redirect-example.com"
+        }
+}

api-ref/source/v2/healthmonitor.inc

@@ -143,6 +143,7 @@ provisioning status.
    - 401
    - 403
    - 404
+   - 409
    - 500
    - 503
 

api-ref/source/v2/index.rst

@@ -35,3 +35,8 @@ Members
 Health Monitor
 --------------
 .. include:: healthmonitor.inc
+
+-----------
+L7 Policies
+-----------
+.. include:: l7policy.inc

api-ref/source/v2/l7policy.inc

@@ -0,0 +1,365 @@
+.. -*- rst -*-
+
+List L7 Policies
+================
+
+.. rest_method:: GET /v2.0/lbaas/l7policies
+
+Lists all L7 policies 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
+   - project_id: project_id_query
+
+Curl Example
+------------
+
+.. literalinclude:: examples/l7policies-list-curl
+   :language: bash
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: ../parameters.yaml
+
+   - action: l7policy-action
+   - admin_state_up: admin_state_up
+   - created_at: created_at
+   - description: description
+   - id: l7policy-id
+   - listener_id: listener-id
+   - name: name
+   - operating_status: operating_status
+   - position: l7policy-position
+   - project_id: project_id
+   - provisioning_status: provisioning_status
+   - redirect_pool_id: l7policy-redirect-pool_id
+   - redirect_url: l7policy-redirect-url
+   - rules: l7policy-rule-ids
+   - updated_at: updated_at
+
+Response Example
+----------------
+
+.. literalinclude:: examples/l7policies-list-response.json
+   :language: javascript
+
+Create an L7 Policy
+===================
+
+.. rest_method:: POST /v2.0/lbaas/l7policies
+
+Creates a L7 policy.
+
+This operation provisions a new L7 policy 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 policy.
+
+In the response, the L7 policy :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}`` to view the progress of
+the provisioning operation. When the L7 policy status changes
+to ``ACTIVE``, the L7 policy 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.
+
+If a new policy is created with a position that matches that of an existing
+policy, then the new policy is inserted at the given position.
+
+.. 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
+
+   - action: l7policy-action
+   - admin_state_up: admin_state_up-default-optional
+   - description: description-optional
+   - listener_id: listener-id
+   - name: name-optional
+   - position: l7policy-position-optional
+   - project_id: project_id-optional
+   - redirect_pool_id: l7policy-redirect-pool_id-optional
+   - redirect_url: l7policy-redirect-url-optional
+
+Request Example
+----------------
+
+.. literalinclude:: examples/l7policy-create-request.json
+   :language: javascript
+
+Curl Example
+------------
+
+.. literalinclude:: examples/l7policy-create-curl
+   :language: bash
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: ../parameters.yaml
+
+   - action: l7policy-action
+   - admin_state_up: admin_state_up
+   - created_at: created_at
+   - description: description
+   - id: l7policy-id
+   - listener_id: listener-id
+   - name: name
+   - operating_status: operating_status
+   - position: l7policy-position
+   - project_id: project_id
+   - provisioning_status: provisioning_status
+   - redirect_pool_id: l7policy-redirect-pool_id
+   - redirect_url: l7policy-redirect-url
+   - rules: l7policy-rule-ids
+   - updated_at: updated_at
+
+Response Example
+----------------
+
+.. literalinclude:: examples/l7policy-create-response.json
+   :language: javascript
+
+Show L7 Policy details
+==========================
+
+.. rest_method:: GET /v2.0/lbaas/l7policies/{l7policy_id}
+
+Shows the details of a L7 policy.
+
+If you are not an administrative user and the L7 policy 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
+
+Curl Example
+------------
+
+.. literalinclude:: examples/l7policy-show-curl
+   :language: bash
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: ../parameters.yaml
+
+   - action: l7policy-action
+   - admin_state_up: admin_state_up
+   - created_at: created_at
+   - description: description
+   - id: l7policy-id
+   - listener_id: listener-id
+   - name: name
+   - operating_status: operating_status
+   - position: l7policy-position
+   - project_id: project_id
+   - provisioning_status: provisioning_status
+   - redirect_pool_id: l7policy-redirect-pool_id
+   - redirect_url: l7policy-redirect-url
+   - rules: l7policy-rule-ids
+   - updated_at: updated_at
+
+
+Response Example
+----------------
+
+.. literalinclude:: examples/l7policy-show-response.json
+   :language: javascript
+
+Update a L7 Policy
+==================
+
+.. rest_method:: PUT /v2.0/lbaas/l7policies/{l7policy_id}
+
+Updates a L7 policy.
+
+If the request is valid, the service returns the ``Accepted (202)``
+response code. To confirm the update, check that the L7 policy
+provisioning status is ``ACTIVE``. If the status is
+``PENDING_UPDATE``, use a GET operation to poll the L7 policy
+object for changes.
+
+This operation returns the updated L7 policy object with the
+``ACTIVE``, ``PENDING_UPDATE``, or ``ERROR`` provisioning status.
+
+If a policy is updated with a position that matches that of an existing
+policy, then the updated policy is inserted at the given position.
+
+.. 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
+
+   - action: l7policy-action-optional
+   - admin_state_up: admin_state_up-default-optional
+   - description: description-optional
+   - l7policy_id: path-l7policy-id
+   - name: name-optional
+   - position: l7policy-position-optional
+   - redirect_pool_id: l7policy-redirect-pool_id-optional
+   - redirect_url: l7policy-redirect-url-optional
+
+Request Example
+---------------
+
+.. literalinclude:: examples/l7policy-update-request.json
+   :language: javascript
+
+Curl Example
+------------
+
+.. literalinclude:: examples/l7policy-update-curl
+   :language: bash
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: ../parameters.yaml
+
+   - action: l7policy-action
+   - admin_state_up: admin_state_up
+   - created_at: created_at
+   - description: description
+   - id: l7policy-id
+   - listener_id: listener-id
+   - name: name
+   - operating_status: operating_status
+   - position: l7policy-position
+   - project_id: project_id
+   - provisioning_status: provisioning_status
+   - redirect_pool_id: l7policy-redirect-pool_id
+   - redirect_url: l7policy-redirect-url
+   - rules: l7policy-rule-ids
+   - updated_at: updated_at
+
+Response Example
+----------------
+
+.. literalinclude:: examples/l7policy-update-response.json
+   :language: javascript
+
+Remove a L7 Policy
+==================
+
+.. rest_method:: DELETE /v2.0/lbaas/l7policies/{l7policy_id}
+
+Removes a L7 policy 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
+
+Curl Example
+------------
+
+.. literalinclude:: examples/l7policy-delete-curl
+   :language: bash
+
+Response
+--------
+
+There is no body content for the response of a successful DELETE request.

api-ref/source/v2/listener.inc

@@ -121,6 +121,7 @@ provisioning status.
    - 401
    - 403
    - 404
+   - 409
    - 500
    - 503
 
@@ -144,7 +145,6 @@ Request
    - protocol: protocol
    - protocol_port: protocol_port
    - sni_container_refs: sni_container_refs-optional
-   - updated_at: updated_at
 
 .. _header_insertions:
 

api-ref/source/v2/member.inc

@@ -134,6 +134,7 @@ provisioning status.
    - 401
    - 403
    - 404
+   - 409
    - 500
    - 503
 

api-ref/source/v2/pool.inc

@@ -149,6 +149,7 @@ provisioning status.
    - 401
    - 403
    - 404
+   - 409
    - 500
    - 503