api-ref: document the address scope extension

Change-Id: Ifd8233ae118059aeae28504bc34d2cb8efb1e4e9
Closes-Bug: #1759959

api-ref/source/v2/address-scopes.inc

@@ -0,0 +1,218 @@
+.. -*- rst -*-
+
+==============
+Address scopes
+==============
+
+Lists, creates, shows details for, updates, and deletes address scopes.
+
+Show address scope
+==================
+
+.. rest_method::  GET /v2.0/address-scopes/{address_scope_id}
+
+Shows information for an address scope.
+
+Use the ``fields`` query parameter to control which fields are returned in the response body.
+For information, see `Filtering and Column Selection <https://wiki.openstack.org/wiki/Neutron/APIv2
+-specification#Filtering_and_Column_Selection>`__.
+
+Normal response codes: 200
+
+Error response codes: 401, 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - address_scope_id: address_scope_id-path
+   - fields: fields
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - address_scope: address_scope
+   - id: address_scope_id_body
+   - name: name
+   - tenant_id: project_id
+   - project_id: project_id
+   - ip_version: ip_version-response
+   - shared: shared-response
+
+Response Example
+----------------
+
+.. literalinclude:: samples/address-scopes/address-scope-show-response.json
+   :language: javascript
+
+Update an address scope
+=======================
+
+.. rest_method::  PUT /v2.0/address-scopes/{address_scope_id}
+
+Updates an address scope.
+
+Normal response codes: 200
+
+Error response codes: 400, 401, 403, 404, 412
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - address_scope_id: address_scope_id-path
+   - address_scope: address_scope
+   - name: name-request
+   - shared: shared
+
+Request Example
+---------------
+
+.. literalinclude:: samples/address-scopes/address-scope-update-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - address_scope: address_scope
+   - id: address_scope_id_body
+   - name: name
+   - tenant_id: project_id
+   - project_id: project_id
+   - ip_version: ip_version-response
+   - shared: shared-response
+
+Response Example
+----------------
+
+.. literalinclude:: samples/address-scopes/address-scope-update-response.json
+   :language: javascript
+
+Delete an address scope
+=======================
+
+.. rest_method::  DELETE /v2.0/address-scopes/{address_scope_id}
+
+Deletes an address scope.
+
+Normal response codes: 204
+
+Error response codes: 401, 404, 412
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - address_scope_id: address_scope_id-path
+
+Response
+--------
+
+There is no body content for the response of a successful DELETE request.
+
+List address scopes
+===================
+
+.. rest_method::  GET /v2.0/address-scopes
+
+Lists address scopes that the project has access to.
+
+Default policy settings return only the address scopes owned by
+the project of the user submitting the request, unless the
+user has administrative role.
+
+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 `Filtering and Column Selection <https://wiki.openstack.org/wiki/Neutron/APIv2
+-specification#Filtering_and_Column_Selection>`__.
+
+Normal response codes: 200
+
+Error response codes: 401
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - id: id-query
+   - name: name-query
+   - tenant_id: project_id-query
+   - project_id: project_id-query
+   - ip_version: ip_version-query
+   - shared: shared-query
+   - fields: fields
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - address_scopes: address_scopes
+   - id: address_scope_id_body
+   - name: name
+   - tenant_id: project_id
+   - project_id: project_id
+   - ip_version: ip_version-response
+   - shared: shared-response
+
+Response Example
+----------------
+
+.. literalinclude:: samples/address-scopes/address-scopes-list-response.json
+   :language: javascript
+
+Create address scope
+====================
+
+.. rest_method::  POST /v2.0/address-scopes
+
+Creates an address scope.
+
+Normal response codes: 201
+
+Error response codes: 400, 401, 403, 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - address_scope: address_scope
+   - name: name-request
+   - tenant_id: project_id-request
+   - project_id: project_id-request
+   - ip_version: ip_version-required
+   - shared: shared
+
+Request Example
+---------------
+
+.. literalinclude:: samples/address-scopes/address-scope-create-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - address_scope: address_scope
+   - id: address_scope_id_body
+   - name: name
+   - tenant_id: project_id
+   - project_id: project_id
+   - ip_version: ip_version-response
+   - shared: shared-response
+
+Response Example
+----------------
+
+.. literalinclude:: samples/address-scopes/address-scope-create-response.json
+   :language: javascript

api-ref/source/v2/index.rst

@@ -24,6 +24,7 @@ Layer 2 Networking
 ##################
 Layer 3 Networking
 ##################
+.. include:: address-scopes.inc
 .. include:: floatingips.inc
 .. include:: routers.inc
 .. include:: subnetpools.inc

api-ref/source/v2/networks.inc

@@ -9,6 +9,15 @@ Networks
 
 Lists, shows details for, creates, updates, and deletes networks.
 
+Address Scopes Extension
+========================
+
+The ``address-scope`` extension adds the ``ipv4_address_scope`` and
+``ipv6_address_scope`` attributes to networks. ``ipv4_address_scope``
+is the ID of the IPv4 address scope that the network is associated with.
+``ipv6_address_scope`` is the ID of the IPv6 address scope that the network
+is associated with.
+
 Auto Allocated Topology
 =======================
 
@@ -156,6 +165,8 @@ Response Parameters
    - created_at: created_at_resource
    - dns_domain: dns_domain
    - id: network-id
+   - ipv4_address_scope: ipv4_address_scope
+   - ipv6_address_scope: ipv6_address_scope
    - l2_adjacency: l2_adjacency
    - mtu: mtu
    - name: network-name
@@ -258,6 +269,8 @@ Response Parameters
    - created_at: created_at_resource
    - dns_domain: dns_domain
    - id: network-id
+   - ipv4_address_scope: ipv4_address_scope
+   - ipv6_address_scope: ipv6_address_scope
    - l2_adjacency: l2_adjacency
    - mtu: mtu
    - name: network-name
@@ -382,6 +395,8 @@ Response Parameters
    - created_at: created_at_resource
    - dns_domain: dns_domain
    - id: network-id
+   - ipv4_address_scope: ipv4_address_scope
+   - ipv6_address_scope: ipv6_address_scope
    - l2_adjacency: l2_adjacency
    - mtu: mtu
    - name: network-name
@@ -490,6 +505,8 @@ Response Parameters
    - created_at: created_at_resource
    - dns_domain: dns_domain
    - id: network-id
+   - ipv4_address_scope: ipv4_address_scope
+   - ipv6_address_scope: ipv6_address_scope
    - l2_adjacency: l2_adjacency
    - mtu: mtu
    - name: network-name
@@ -587,6 +604,8 @@ Response Parameters
    - created_at: created_at_resource
    - dns_domain: dns_domain
    - id: network-id
+   - ipv4_address_scope: ipv4_address_scope
+   - ipv6_address_scope: ipv6_address_scope
    - l2_adjacency: l2_adjacency
    - mtu: mtu
    - name: network-name

api-ref/source/v2/parameters.yaml

@@ -1,6 +1,12 @@
  # variables in header
 
 # variables in path
+address_scope_id-path:
+  description: |
+    The ID of the address scope.
+  in: path
+  required: true
+  type: string
 agent_id-path:
   description: |
     The ID of the agent.
@@ -863,12 +869,30 @@ address:
   in: body
   required: true
   type: string
+address_scope:
+  description: |
+    An ``address scope`` object.
+  in: body
+  required: true
+  type: object
 address_scope_id:
   description: |
     An address scope to assign to the subnet pool.
   in: body
   required: false
+  type: object
+address_scope_id_body:
+  description: |
+    The ID of the address scope.
+  in: body
+  required: true
   type: string
+address_scopes:
+  description: |
+    A list of ``address scope`` objects.
+  in: body
+  required: true
+  type: array
 admin_state_up:
   description: |
     The administrative state of the resource, which is
@@ -2749,6 +2773,12 @@ ip_version:
   in: body
   required: false
   type: integer
+ip_version-required:
+  description: |
+    The IP protocol version. Valid value is ``4`` or ``6``.
+  in: body
+  required: true
+  type: integer
 ip_version-response:
   description: |
     The IP protocol version. Valid value is ``4`` or
@@ -2811,6 +2841,18 @@ ipsecpolicy_id-body-response:
   in: body
   required: true
   type: string
+ipv4_address_scope:
+  description: |
+    The ID of the IPv4 address scope that the network is associated with.
+  in: body
+  required: true
+  type: string
+ipv6_address_scope:
+  description: |
+    The ID of the IPv6 address scope that the network is associated with.
+  in: body
+  required: true
+  type: string
 l2_adjacency:
   description: |
     Indicates whether L2 connectivity is available throughout

api-ref/source/v2/samples/address-scopes/address-scope-create-request.json

@@ -0,0 +1,9 @@
+{
+    "address_scope": {
+        "name": "address-scope-2",
+        "tenant_id": "a7a7fa10fd7a4c80acb7e4b224480495",
+        "ip_version": 4,
+        "shared": true,
+        "project_id": "a7a7fa10fd7a4c80acb7e4b224480495"
+    }
+}

api-ref/source/v2/samples/address-scopes/address-scope-create-response.json

@@ -0,0 +1,10 @@
+{
+    "address_scope": {
+        "name": "address-scope-2",
+        "tenant_id": "a7a7fa10fd7a4c80acb7e4b224480495",
+        "ip_version": 4,
+        "shared": true,
+        "project_id": "a7a7fa10fd7a4c80acb7e4b224480495",
+        "id": "4143da3e-d2a7-4077-ba80-215ecfd016d7"
+    }
+}

api-ref/source/v2/samples/address-scopes/address-scope-show-response.json

@@ -0,0 +1,10 @@
+{
+    "address_scope": {
+        "name": "address-scope-ip4",
+        "tenant_id": "a7a7fa10fd7a4c80acb7e4b224480495",
+        "ip_version": 4,
+        "shared": true,
+        "project_id": "a7a7fa10fd7a4c80acb7e4b224480495",
+        "id": "4143da3e-d2a7-4077-ba80-215ecfd016d7"
+    }
+}

api-ref/source/v2/samples/address-scopes/address-scope-update-request.json

@@ -0,0 +1,6 @@
+{
+    "address_scope": {
+        "name": "address-scope-ip4",
+        "shared": true
+    }
+}

api-ref/source/v2/samples/address-scopes/address-scope-update-response.json

@@ -0,0 +1,10 @@
+{
+    "address_scope": {
+        "name": "address-scope-2",
+        "tenant_id": "a7a7fa10fd7a4c80acb7e4b224480495",
+        "ip_version": 4,
+        "shared": true,
+        "project_id": "a7a7fa10fd7a4c80acb7e4b224480495",
+        "id": "4143da3e-d2a7-4077-ba80-215ecfd016d7"
+    }
+}

api-ref/source/v2/samples/address-scopes/address-scopes-list-response.json

@@ -0,0 +1,20 @@
+{
+    "address_scopes": [
+        {
+            "name": "address-scope-ip6",
+            "tenant_id": "a7a7fa10fd7a4c80acb7e4b224480495",
+            "ip_version": 6,
+            "shared": true,
+            "project_id": "a7a7fa10fd7a4c80acb7e4b224480495",
+            "id": "3b189848-58bb-4499-abc2-8df170a6a8ae"
+        },
+        {
+            "name": "address-scope-2",
+            "tenant_id": "a7a7fa10fd7a4c80acb7e4b224480495",
+            "ip_version": 4,
+            "shared": true,
+            "project_id": "a7a7fa10fd7a4c80acb7e4b224480495",
+            "id": "4143da3e-d2a7-4077-ba80-215ecfd016d7"
+        }
+    ]
+}

api-ref/source/v2/samples/networks/network-create-response.json

@@ -8,6 +8,8 @@
         "created_at": "2016-03-08T20:19:41",
         "dns_domain": "my-domain.org.",
         "id": "4e8e5957-649f-477b-9e5b-f1f75b21c03c",
+        "ipv4_address_scope": null,
+        "ipv6_address_scope": null,
         "l2_adjacency": true,
         "mtu": 1400,
         "name": "net1",

api-ref/source/v2/samples/networks/network-multi-create-response.json

@@ -10,6 +10,8 @@
         "name": "net1",
         "admin_state_up": true,
         "dns_domain": "",
+        "ipv4_address_scope": null,
+        "ipv6_address_scope": null,
         "l2_adjacency": true,
         "mtu": 1500,
         "port_security_enabled": true,

api-ref/source/v2/samples/networks/network-multi-show-response.json

@@ -8,6 +8,8 @@
         "created_at": "2016-03-08T20:19:41",
         "dns_domain": "my-domain.org.",
         "id": "4e8e5957-649f-477b-9e5b-f1f75b21c03c",
+        "ipv4_address_scope": null,
+        "ipv6_address_scope": null,
         "l2_adjacency": false,
         "mtu": 1500,
         "name": "net1",

api-ref/source/v2/samples/networks/network-provider-create-response.json

@@ -8,6 +8,8 @@
         ],
         "created_at": "2016-03-08T20:19:41",
         "dns_domain": "",
+        "ipv4_address_scope": null,
+        "ipv6_address_scope": null,
         "name": "net1",
         "provider:physical_network": "public",
         "admin_state_up": true,

api-ref/source/v2/samples/networks/network-provider-show-response.json

@@ -8,6 +8,8 @@
         "created_at": "2016-03-08T20:19:41",
         "dns_domain": "my-domain.org.",
         "id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
+        "ipv4_address_scope": null,
+        "ipv6_address_scope": null,
         "l2_adjacency": false,
         "mtu": 1500,
         "name": "private-network",

api-ref/source/v2/samples/networks/network-show-response.json

@@ -8,6 +8,8 @@
         "created_at": "2016-03-08T20:19:41",
         "dns_domain": "my-domain.org.",
         "id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
+        "ipv4_address_scope": null,
+        "ipv6_address_scope": null,
         "l2_adjacency": false,
         "mtu": 1500,
         "name": "private-network",

api-ref/source/v2/samples/networks/network-update-response.json

@@ -8,6 +8,8 @@
         "created_at": "2016-03-08T20:19:41",
         "dns_domain": "my-domain.org.",
         "id": "1f370095-98f6-4079-be64-6d3d4a6adcc6",
+        "ipv4_address_scope": null,
+        "ipv6_address_scope": null,
         "l2_adjacency": false,
         "mtu": 1300,
         "name": "sample_network_5_updated",

api-ref/source/v2/samples/networks/networks-bulk-create-response.json

@@ -9,6 +9,8 @@
             "created_at": "2016-03-08T20:19:41",
             "dns_domain": "",
             "id": "bc1a76cb-8767-4c3a-bb95-018b822f2130",
+            "ipv4_address_scope": null,
+            "ipv6_address_scope": null,
             "l2_adjacency": true,
             "mtu": 1500,
             "name": "sample_network3",
@@ -35,6 +37,8 @@
             "created_at": "2016-03-08T20:19:41",
             "dns_domain": "",
             "id": "af374017-c9ae-4a1d-b799-ab73111476e2",
+            "ipv4_address_scope": null,
+            "ipv6_address_scope": null,
             "l2_adjacency": true,
             "mtu": 1500,
             "name": "sample_network4",

api-ref/source/v2/samples/networks/networks-list-response.json

@@ -9,6 +9,8 @@
             "created_at": "2016-03-08T20:19:41",
             "dns_domain": "my-domain.org.",
             "id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
+            "ipv4_address_scope": null,
+            "ipv6_address_scope": null,
             "l2_adjacency": false,
             "mtu": 1500,
             "name": "net1",
@@ -37,6 +39,8 @@
             "created_at": "2016-03-08T20:19:41",
             "dns_domain": "my-domain.org.",
             "id": "db193ab3-96e3-4cb3-8fc5-05f4296d0324",
+            "ipv4_address_scope": null,
+            "ipv6_address_scope": null,
             "l2_adjacency": false,
             "mtu": 1500,
             "name": "net2",

api-ref/source/v2/samples/networks/networks-provider-list-response.json

@@ -9,6 +9,8 @@
             "created_at": "2016-03-08T20:19:41",
             "dns_domain": "my-domain.org.",
             "id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
+            "ipv4_address_scope": null,
+            "ipv6_address_scope": null,
             "l2_adjacency": false,
             "mtu": 1500,
             "name": "net1",
@@ -39,6 +41,8 @@
             "created_at": "2016-03-08T20:19:41",
             "dns_domain": "my-domain.org.",
             "id": "db193ab3-96e3-4cb3-8fc5-05f4296d0324",
+            "ipv4_address_scope": null,
+            "ipv6_address_scope": null,
             "l2_adjacency": false,
             "mtu": 1450,
             "name": "net2",

api-ref/source/v2/subnetpools.inc

@@ -7,6 +7,13 @@ Subnet pools extension (subnetpools)
 Lists, creates, shows details for, updates, and deletes subnet
 pools.
 
+Address Scopes Extension
+========================
+
+The ``address-scope`` extension adds the ``address_scope_id`` attribute to
+subnet pools. ``address_scope_id`` is the ID of the address scope that the
+subnet pool belongs to.
+
 Show subnet pool
 ================