[Docs] Add api-ref for the address groups

Related-blueprint: bp/address-groups-in-sg-rules
Change-Id: Ied4947ce0d52b84e501cac117f29882d6e6dba98

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

@@ -0,0 +1,305 @@
+.. -*- rst -*-
+
+==============
+Address groups
+==============
+
+Lists, creates, shows details for, updates, and deletes address groups.
+
+Show address group
+==================
+
+.. rest_method::  GET /v2.0/address-groups/{address_group_id}
+
+Shows information for an address group.
+
+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_group_id: address_group_id-path
+   - fields: fields
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - address_group: address_group
+   - id: address_group_id_body
+   - name: name
+   - description: description
+   - tenant_id: project_id
+   - project_id: project_id
+   - addresses: addresses
+
+Response Example
+----------------
+
+.. literalinclude:: samples/address-groups/address-group-show-response.json
+   :language: javascript
+
+Update an address group
+=======================
+
+.. rest_method::  PUT /v2.0/address-groups/{address_group_id}
+
+Updates an address group.
+
+Normal response codes: 200
+
+Error response codes: 400, 401, 403, 404, 412
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - address_group_id: address_group_id-path
+   - address_group: address_group
+   - name: name-request
+   - description: description
+
+Request Example
+---------------
+
+.. literalinclude:: samples/address-groups/address-group-update-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - address_group: address_group
+   - id: address_group_id_body
+   - name: name
+   - description: description
+   - tenant_id: project_id
+   - project_id: project_id
+   - addresses: addresses
+
+Response Example
+----------------
+
+.. literalinclude:: samples/address-groups/address-group-update-response.json
+   :language: javascript
+
+Delete an address group
+=======================
+
+.. rest_method::  DELETE /v2.0/address-groups/{address_group_id}
+
+Deletes an address group.
+
+Normal response codes: 204
+
+Error response codes: 401, 404, 412
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - address_group_id: address_group_id-path
+
+Response
+--------
+
+There is no body content for the response of a successful DELETE request.
+
+List address groups
+===================
+
+.. rest_method::  GET /v2.0/address-groups
+
+Lists address groups that the project has access to.
+
+Default policy settings return only the address groups 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
+   - sort_key: address_group-sort_key
+   - fields: fields
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - address_groups: address_groups
+   - id: address_group_id_body
+   - name: name
+   - tenant_id: project_id
+   - project_id: project_id
+   - addresses: addresses
+
+Response Example
+----------------
+
+.. literalinclude:: samples/address-groups/address-groups-list-response.json
+   :language: javascript
+
+Create address group
+====================
+
+.. rest_method::  POST /v2.0/address-groups
+
+Creates an address group.
+
+Normal response codes: 201
+
+Error response codes: 400, 401, 403, 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - address_group_id: address_group_id-path
+   - address_group: address_group
+   - name: name-request
+   - description: description
+   - addresses: addresses
+
+Request Example
+---------------
+
+.. literalinclude:: samples/address-groups/address-group-create-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - address_group: address_group
+   - id: address_group_id_body
+   - name: name
+   - description: description
+   - tenant_id: project_id
+   - project_id: project_id
+   - addresses: addresses
+
+Response Example
+----------------
+
+.. literalinclude:: samples/address-groups/address-group-create-response.json
+   :language: javascript
+
+Add IP addresses to address group
+=================================
+
+.. rest_method::  PUT /v2.0/address-group/{address_group_id}/add_addresses
+
+Atomically adds a set of IP addresses to the address group's already existing
+addresses.
+
+Normal response codes: 200
+
+Error response codes: 400, 401, 404, 412
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - address_group_id: address_group_id-path
+   - addresses: addresses
+
+Request Example
+---------------
+
+.. literalinclude:: samples/address-groups/address-group-add-addresses-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - address_group: address_group
+   - id: address_group_id_body
+   - name: name
+   - description: description
+   - tenant_id: project_id
+   - project_id: project_id
+   - addresses: addresses
+
+Response Example
+----------------
+
+.. literalinclude:: samples/address-groups/address-group-add-addresses-response.json
+   :language: javascript
+
+Remove IP addresses to address group
+====================================
+
+.. rest_method::  PUT /v2.0/address-group/{address_group_id}/remove_addresses
+
+Atomically removes a set of IP addresses from the address group's already
+existing addresses.
+
+Normal response codes: 200
+
+Error response codes: 400, 401, 404, 412
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - address_group_id: address_group_id-path
+   - addresses: addresses
+
+Request Example
+---------------
+
+.. literalinclude:: samples/address-groups/address-group-remove-addresses-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - address_group: address_group
+   - id: address_group_id_body
+   - name: name
+   - description: description
+   - tenant_id: project_id
+   - project_id: project_id
+   - addresses: addresses
+
+Response Example
+----------------
+
+.. literalinclude:: samples/address-groups/address-group-remove-addresses-response.json
+   :language: javascript

api-ref/source/v2/index.rst

@@ -37,6 +37,7 @@ Layer 3 Networking
 ########
 Security
 ########
+.. include:: address-groups.inc
 .. include:: fwaas-v2.inc
 .. include:: rbac-policy.inc
 .. include:: security-group-rules.inc

api-ref/source/v2/parameters.yaml

@@ -1,6 +1,12 @@
  # variables in header
 
 # variables in path
+address_group_id-path:
+  description: |
+    The ID of the address group.
+  in: path
+  required: true
+  type: string
 address_scope_id-path:
   description: |
     The ID of the address scope.
@@ -298,6 +304,19 @@ vpnservice_id-path:
   required: true
   type: string
 # variables in query
+address_group-sort_key:
+  description: |
+    Sorts by an address group attribute. You can specify multiple pairs of sort
+    key and sort direction query parameters. The sort keys are limited to:
+
+    - ``id``
+    - ``name``
+    - ``project_id``
+    - ``shared``
+    - ``tenant_id``
+  in: query
+  required: false
+  type: string
 address_scope-sort_key:
   description: |
     Sorts by an address scope attribute. You can specify multiple pairs of sort
@@ -1527,6 +1546,24 @@ address:
   in: body
   required: true
   type: string
+address_group:
+  description: |
+    An ``address group`` object.
+  in: body
+  required: true
+  type: object
+address_group_id_body:
+  description: |
+    The ID of the address group.
+  in: body
+  required: true
+  type: string
+address_groups:
+  description: |
+    A list of ``address group`` objects.
+  in: body
+  required: true
+  type: array
 address_scope:
   description: |
     An ``address scope`` object.
@@ -1551,6 +1588,12 @@ address_scopes:
   in: body
   required: true
   type: array
+addresses:
+  description: |
+    A list of IP addresses.
+  in: body
+  required: true
+  type: array
 admin_state_up:
   description: |
     The administrative state of the resource, which is

api-ref/source/v2/samples/address-groups/address-group-add-addresses-request.json

@@ -0,0 +1,5 @@
+{
+    "address_group": {
+        "addresses": ["10.0.2.100/32"]
+    }
+}

api-ref/source/v2/samples/address-groups/address-group-add-addresses-response.json

@@ -0,0 +1,14 @@
+{
+    "address_group": {
+        "id": "9ace2ef6-bd57-426a-9223-cf1751d26db9",
+        "name": "doc-address-group",
+        "project_id": "c9a6f447205640e89523df967c26f4d5",
+        "addresses": [
+            "10.0.1.34/32",
+            "10.0.2.100/32",
+            "192.168.100.0/24"
+        ],
+        "description": "AG description",
+        "tenant_id": "c9a6f447205640e89523df967c26f4d5"
+    }
+}

api-ref/source/v2/samples/address-groups/address-group-create-request.json

@@ -0,0 +1,7 @@
+{
+    "address_group": {
+        "addresses": [],
+        "name": "address-group-2",
+        "description": "docs example group"
+    }
+}

api-ref/source/v2/samples/address-groups/address-group-create-response.json

@@ -0,0 +1,10 @@
+{
+    "address_group": {
+        "id": "9f60873a-9bb0-45c9-ac25-b1d5d668d955",
+        "name": "address-group-2",
+        "project_id": "c9a6f447205640e89523df967c26f4d5",
+        "addresses": [],
+        "description": "docs example group",
+        "tenant_id": "c9a6f447205640e89523df967c26f4d5"
+    }
+}

api-ref/source/v2/samples/address-groups/address-group-remove-addresses-request.json

@@ -0,0 +1,5 @@
+{
+    "address_group": {
+        "addresses": ["10.0.2.100/32"]
+    }
+}

api-ref/source/v2/samples/address-groups/address-group-remove-addresses-response.json

@@ -0,0 +1,13 @@
+{
+    "address_group": {
+        "id": "9ace2ef6-bd57-426a-9223-cf1751d26db9",
+        "name": "doc-address-group",
+        "project_id": "c9a6f447205640e89523df967c26f4d5",
+        "addresses": [
+            "10.0.1.34/32",
+            "192.168.100.0/24"
+        ],
+        "description": "AG description",
+        "tenant_id": "c9a6f447205640e89523df967c26f4d5"
+    }
+}

api-ref/source/v2/samples/address-groups/address-group-show-response.json

@@ -0,0 +1,10 @@
+{
+  "addresses": [
+    "10.0.1.34/32",
+    "192.168.100.0/24"
+  ],
+  "description": "",
+  "id": "9ace2ef6-bd57-426a-9223-cf1751d26db9",
+  "name": "doc-address-group",
+  "project_id": "c9a6f447205640e89523df967c26f4d5"
+}

api-ref/source/v2/samples/address-groups/address-group-update-request.json

@@ -0,0 +1,5 @@
+{
+    "address_group": {
+        "description": "AG description"
+    }
+}

api-ref/source/v2/samples/address-groups/address-group-update-response.json

@@ -0,0 +1,14 @@
+{
+    "address_group": {
+        "id": "9ace2ef6-bd57-426a-9223-cf1751d26db9",
+        "name": "doc-address-group",
+        "project_id": "c9a6f447205640e89523df967c26f4d5",
+        "addresses": [
+            "10.0.1.34/32",
+            "10.0.2.100/32",
+            "192.168.100.0/24"
+        ],
+        "description": "AG description",
+        "tenant_id": "c9a6f447205640e89523df967c26f4d5"
+    }
+}

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

@@ -0,0 +1,16 @@
+{
+    "address_groups": [
+        {
+            "id": "9ace2ef6-bd57-426a-9223-cf1751d26db9",
+            "name": "doc-address-group",
+            "project_id": "c9a6f447205640e89523df967c26f4d5",
+            "addresses": [
+                "10.0.1.34/32",
+                "10.0.2.100/32",
+                "192.168.100.0/24"
+            ],
+            "description": "",
+            "tenant_id": "c9a6f447205640e89523df967c26f4d5"
+        }
+    ]
+}