api-ref: add availability_zone extension

Depends-On: Id882f949cc73a34290c311f3ce3d69d1b809c29f
Change-Id: Icbf427f20ca912a40d68e8042abeeabffeb3005f
Closes-Bug: #1733362

api-ref/source/v2/agents.inc

@@ -6,6 +6,13 @@ Agents
 
 Lists, shows details for, updates, and deletes agents.
 
+Availability Zone Extension
+===========================
+
+The ``availability_zone`` extension adds the ``availability_zone`` attribute
+to agents. ``availability_zone`` is the name of the availability zone that
+the agent is running on.
+
 List all agents
 ===============
 
@@ -31,6 +38,7 @@ Request
    - admin_state_up: admin_state_up-query
    - agent_type: agent_type-query
    - alive: alive-query
+   - availability_zone: availability_zone-query
    - binary: binary-query
    - description: description-query
    - host: host-query
@@ -47,6 +55,7 @@ Response Parameters
    - agents: agents
    - agent_type: agent_type
    - alive: alive
+   - availability_zone: availability_zone
    - binary: binary
    - configurations: configurations
    - created_at: created_at_resource
@@ -92,6 +101,7 @@ Response Parameters
    - agent: agent
    - agent_type: agent_type
    - alive: alive
+   - availability_zone: availability_zone
    - binary: binary
    - configurations: configurations
    - created_at: created_at_resource
@@ -144,6 +154,7 @@ Response Parameters
    - agent: agent
    - agent_type: agent_type
    - alive: alive
+   - availability_zone: availability_zone
    - binary: binary
    - configurations: configurations
    - created_at: created_at_resource

api-ref/source/v2/availability_zones.inc

@@ -0,0 +1,43 @@
+.. -*- rst -*-
+
+==================
+Availability Zones
+==================
+
+Lists availability zones.
+
+List all availability zones
+===========================
+
+.. rest_method::  GET /v2.0/availability_zones
+
+Lists all availability zones.
+
+Normal response codes: 200
+
+Error response codes: 401
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - state: state-query
+   - resource: resource-query
+   - name: name-query
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - availability_zones: availability_zones-list
+   - state: state
+   - resource: resource
+   - name: name
+
+Response Example
+----------------
+
+.. literalinclude:: samples/availability-zones/azs-list-response.json
+   :language: javascript

api-ref/source/v2/index.rst

@@ -85,6 +85,7 @@ Logging
 Networking Agents
 #################
 .. include:: agents.inc
+.. include:: availability_zones.inc
 .. include:: l3-agent-scheduler.inc
 #######################
 Auto Allocated Topology

api-ref/source/v2/parameters.yaml

@@ -358,6 +358,12 @@ alive-query:
   in: query
   required: false
   type: boolean
+availability_zone-query:
+  description: |
+    Filter the list result by the availability zone of the agent.
+  in: query
+  required: false
+  type: string
 binary-query:
   description: |
     Filter the list result by the executable command used to start the agent
@@ -955,6 +961,13 @@ remote_ip_prefix-query:
   in: query
   required: false
   type: string
+resource-query:
+  description: |
+    Filter the list result by the resource type of the availability zone.
+    The supported resource types are ``network`` and ``router``.
+  in: query
+  required: false
+  type: string
 resource_log_id-query:
   description: |
     Filter the log list result by the ID of resource (e.g security group ID).
@@ -1098,6 +1111,13 @@ sort_dir:
   in: query
   required: false
   type: string
+state-query:
+  description: |
+    Filter the list result by the state of the availability zone, which is
+    either ``available`` or ``unavailable``.
+  in: query
+  required: false
+  type: string
 subnet-enable_dhcp-query:
   description: |
     Filter the subnet list result based on if is enabled or disabled
@@ -1426,6 +1446,12 @@ auth_mode:
   in: body
   required: false
   type: string
+availability_zone:
+  description: |
+    The availability zone of the agent.
+  in: body
+  required: true
+  type: string
 availability_zone_hints:
   description: |
     The availability zone candidate for the network.
@@ -1444,6 +1470,12 @@ availability_zones:
   in: body
   required: true
   type: array
+availability_zones-list:
+  description: |
+    A list of ``availability zone`` objects.
+  in: body
+  required: true
+  type: array
 bandwidth_limit_rule:
   description: |
     A ``bandwidth_limit_rule`` object.
@@ -4683,6 +4715,13 @@ remote_ip_prefix-request:
   in: body
   required: false
   type: string
+resource:
+  description: |
+    The resource type of the availability zone. The supported resource types
+    are ``network`` and ``router``.
+  in: body
+  required: true
+  type: string
 resource-collection:
   description: |
     Collection name of the resource.
@@ -5329,6 +5368,13 @@ started_at:
   in: body
   required: true
   type: string
+state:
+  description: |
+    The state of the availability zone, which is either ``available`` or
+    ``unavailable``.
+  in: body
+  required: true
+  type: string
 status_description:
   description: |
     Human-readable description of the status.

api-ref/source/v2/samples/availability-zones/azs-list-response.json

@@ -0,0 +1,14 @@
+{
+    "availability_zones": [
+        {
+            "state": "available",
+            "resource": "router",
+            "name": "nova"
+        },
+        {
+            "state": "available",
+            "resource": "network",
+            "name": "nova"
+        }
+    ]
+}