From 10907011b72afda23e31dc199fb0259e6df6c92c Mon Sep 17 00:00:00 2001 From: Anindita Das <anindita.das@intel.com> Date: Sat, 20 Aug 2016 22:35:20 +0000 Subject: [PATCH] api-ref: Fix api-ref for subnets Added request/response parameters for the rest_method:: GET /v2.0/subnets POST /v2.0/subnets (Create Subnet) POST /v2.0/subnets (Bulk Create Subnet) GET /v2.0/subnets/{subnet_id} (Show Subnet Details) PUT /v2.0/subnets/{subnet_id} (Update Subnet) DELETE /v2.0/subnets/{subnet_id} (Delete Subnet) Co-Authored-By: Akihiro Motoki <amotoki@gmail.com> Change-Id: I7cfba70c6805161ee9e26135fe08f5075e94d755 Partially-Implements: blueprint neutron-in-tree-api-ref Partial-Bug: #1613151 --- api-ref/source/v2/parameters.yaml | 256 +++++++++++++++--- .../subnets/subnet-create-request.json | 2 +- .../subnets/subnet-create-response.json | 10 +- .../samples/subnets/subnet-show-response.json | 8 +- .../subnets/subnets-create-bulk-response.json | 20 +- .../subnets/subnets-list-response.json | 20 +- api-ref/source/v2/subnets.inc | 235 +++++++++++++++- 7 files changed, 488 insertions(+), 63 deletions(-) diff --git a/api-ref/source/v2/parameters.yaml b/api-ref/source/v2/parameters.yaml index e2209cf11..59feda247 100644 --- a/api-ref/source/v2/parameters.yaml +++ b/api-ref/source/v2/parameters.yaml @@ -169,11 +169,11 @@ service_id: in: path required: false type: string -subnet_id_2: +subnet_id-path: description: | - The UUID of the subnet. + The ID of the subnet. in: path - required: false + required: true type: string subnetpool_id: description: | @@ -1835,12 +1835,6 @@ ip_version_1: in: body required: true type: integer -ip_version_2: - description: | - The IP protocol version. Value is ``4`` or ``6``. - in: body - required: true - type: integer ip_version_3: description: | The IP version (4 or 6) of the subnet. @@ -3821,6 +3815,209 @@ sub_ports: in: body required: true type: array +subnet-allocation_pools: + description: | + Allocation pools with ``start`` and ``end`` IP addresses + for this subnet. + in: body + required: true + type: array +subnet-allocation_pools-request: + description: | + Allocation pools with ``start`` and ``end`` IP addresses + for this subnet. If allocation_pools are not specified, OpenStack + Networking automatically allocates pools for covering all IP addresses + in the CIDR, excluding the address reserved for the subnet gateway by + default. + in: body + required: false + type: array +subnet-created_at: + description: | + Time at which the subnet has been created. + in: body + required: true + type: string +subnet-description: + description: | + Description of the subnet. + in: body + required: true + type: string +subnet-dns_nameservers: + description: | + List of dns name servers associated with the subnet. + in: body + required: true + type: array +subnet-dns_nameservers-request: + description: | + List of dns name servers associated with the subnet. Default is an + empty list. + in: body + required: false + type: array +subnet-enable_dhcp: + description: | + Indicates whether dhcp is enabled or disabled + for the subnet. + in: body + required: true + type: boolean +subnet-enable_dhcp-request: + description: | + Indicates whether dhcp is enabled or disabled + for the subnet. Default is ``true``. + in: body + required: false + type: boolean +subnet-gateway_ip: + description: | + Gateway IP of this subnet. If the value is ``null`` that implies no + gateway is associated with the subnet. + in: body + required: true + type: string +subnet-gateway_ip-request: + description: | + Gateway IP of this subnet. If the value is ``null`` that implies no + gateway is associated with the subnet. If the gateway_ip is not + specified, OpenStack Networking allocates an address from the CIDR + for the gateway for the subnet by default. + in: body + required: false + type: string +subnet-host_routes: + description: | + Additional routes for the subnet. A list of dictionaries with + ``destination`` and ``nexthop`` parameters. + in: body + required: true + type: array +subnet-host_routes-request: + description: | + Additional routes for the subnet. A list of dictionaries with + ``destination`` and ``nexthop`` parameters. Default value is + an empty list. + in: body + required: false + type: array +subnet-id-body: + description: | + The ID of the subnet. + in: body + required: true + type: string +subnet-ip_version: + description: | + The IP protocol version. Value is ``4`` or ``6``. + in: body + required: true + type: integer +subnet-ipv6_address_mode: + description: | + The IPv6 address modes specifies mechanisms for assigning IP addresses. + Value is ``slaac``, ``dhcpv6-stateful``, ``dhcpv6-stateless`` or ``null``. + in: body + required: true + type: string +subnet-ipv6_address_mode-request: + description: | + The IPv6 address modes specifies mechanisms for assigning IP addresses. + Value is ``slaac``, ``dhcpv6-stateful``, ``dhcpv6-stateless``. + in: body + required: false + type: string +subnet-ipv6_ra_mode: + description: | + The IPv6 router advertisement specifies whether the networking service + should transmit ICMPv6 packets, for a subnet. Value is ``slaac``, + ``dhcpv6-stateful``, ``dhcpv6-stateless`` or ``null``. + in: body + required: true + type: string +subnet-ipv6_ra_mode-request: + description: | + The IPv6 router advertisement specifies whether the networking service + should transmit ICMPv6 packets, for a subnet. Value is ``slaac``, + ``dhcpv6-stateful``, ``dhcpv6-stateless``. + in: body + required: false + type: string +subnet-name: + description: | + Human-readable name of the resource. + in: body + required: true + type: string +subnet-name-request: + description: | + Human-readable name of the resource. Default is an empty string. + in: body + required: false + type: string +subnet-name-update-request: + description: | + Human-readable name of the resource. + in: body + required: false + type: string +subnet-network_id: + description: | + The ID of the network to which the subnet belongs. + in: body + required: true + type: string +subnet-obj: + description: | + A ``subnet`` object. + in: body + required: true + type: string +subnet-revision_number: + description: | + The revision number of the subnet. + in: body + required: true + type: string +subnet-segment_id: + description: | + The ID of a network segment the subnet is associated with. + It is available when ``segment`` extension is enabled. + in: body + required: true + type: string +subnet-segment_id-request: + description: | + The ID of a network segment the subnet is associated with. + It is available when ``segment`` extension is enabled. + in: body + required: false + type: string +subnet-service_types: + description: | + The service types associated with the subnet. + in: body + required: true + type: string +subnet-subnetpool_id: + description: | + The ID of the subnet pool associated with the subnet. + in: body + required: true + type: string +subnet-subnetpool_id-request: + description: | + The ID of the subnet pool associated with the subnet. + in: body + required: false + type: string +subnet-updated_at: + description: | + Time at which the subnet has been updated. + in: body + required: true + type: string subnet_id: description: | If you specify only a subnet UUID, OpenStack @@ -3830,41 +4027,6 @@ subnet_id: in: body required: false type: string -subnet_id_1: - description: | - The UUID of the subnet to which the port is - attached. - in: body - required: true - type: string -subnet_id_3: - description: | - (Deprecated) The subnet where the VPN service should - be provided. - in: body - required: false - type: string -subnet_id_4: - description: | - (Deprecated) The subnet where the VPN service should - be provided. - in: body - required: true - type: string -subnet_id_6: - description: | - If you omit this parameter, LBaaS uses the - ``vip_subnet_id`` parameter value for the subnet UUID. - in: body - required: false - type: integer -subnet_id_7: - description: | - The UUID of the subnet on which to allocate the - virtual IP (VIP) address. - in: body - required: true - type: string subnet_ip_availability: description: | This is dictionary showing subnet IP @@ -3897,6 +4059,12 @@ subnets: in: body required: true type: array +subnets-obj: + description: | + A list of ``subnet`` objects. + in: body + required: true + type: array subnets_1: description: | The associated subnets. diff --git a/api-ref/source/v2/samples/subnets/subnet-create-request.json b/api-ref/source/v2/samples/subnets/subnet-create-request.json index d12c6ddb6..f5f18841a 100644 --- a/api-ref/source/v2/samples/subnets/subnet-create-request.json +++ b/api-ref/source/v2/samples/subnets/subnet-create-request.json @@ -2,6 +2,6 @@ "subnet": { "network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22", "ip_version": 4, - "cidr": "10.0.0.1" + "cidr": "192.168.199.0/24" } } diff --git a/api-ref/source/v2/samples/subnets/subnet-create-response.json b/api-ref/source/v2/samples/subnets/subnet-create-response.json index 07dfce611..27c1e0b5c 100644 --- a/api-ref/source/v2/samples/subnets/subnet-create-response.json +++ b/api-ref/source/v2/samples/subnets/subnet-create-response.json @@ -17,6 +17,14 @@ "ip_version": 4, "gateway_ip": "192.168.199.1", "cidr": "192.168.199.0/24", - "id": "3b80198d-4f7b-4f77-9ef5-774d54e17126" + "id": "3b80198d-4f7b-4f77-9ef5-774d54e17126", + "created_at": "2016-10-10T14:35:47Z", + "description": "", + "ipv6_address_mode": null, + "ipv6_ra_mode": null, + "revision_number": 2, + "service_types": [], + "subnetpool_id": null, + "updated_at": "2016-10-10T14:35:47Z" } } diff --git a/api-ref/source/v2/samples/subnets/subnet-show-response.json b/api-ref/source/v2/samples/subnets/subnet-show-response.json index ac34ea9a6..52e1b3c53 100644 --- a/api-ref/source/v2/samples/subnets/subnet-show-response.json +++ b/api-ref/source/v2/samples/subnets/subnet-show-response.json @@ -19,6 +19,12 @@ "gateway_ip": "192.0.0.1", "cidr": "192.0.0.0/8", "updated_at": "2016-03-08T20:19:41", - "id": "54d6f61d-db07-451c-9ab3-b9609b6b6f0b" + "id": "54d6f61d-db07-451c-9ab3-b9609b6b6f0b", + "description": "", + "ipv6_address_mode": null, + "ipv6_ra_mode": null, + "revision_number": 2, + "service_types": [], + "subnetpool_id": null } } diff --git a/api-ref/source/v2/samples/subnets/subnets-create-bulk-response.json b/api-ref/source/v2/samples/subnets/subnets-create-bulk-response.json index 1bdb643bb..d890e3537 100644 --- a/api-ref/source/v2/samples/subnets/subnets-create-bulk-response.json +++ b/api-ref/source/v2/samples/subnets/subnets-create-bulk-response.json @@ -18,7 +18,15 @@ "network_id": "e6031bc2-901a-4c66-82da-f4c32ed89406", "segment_id": null, "project_id": "d19231fc08ec4bc4829b668040d34512", - "tenant_id": "d19231fc08ec4bc4829b668040d34512" + "tenant_id": "d19231fc08ec4bc4829b668040d34512", + "created_at": "2016-10-10T14:35:47Z", + "description": "", + "ipv6_address_mode": null, + "ipv6_ra_mode": null, + "revision_number": 2, + "service_types": [], + "subnetpool_id": null, + "updated_at": "2016-10-10T14:35:47Z" }, { "allocation_pools": [ @@ -38,7 +46,15 @@ "network_id": "64239a54-dcc4-4b39-920b-b37c2144effa", "segment_id": null, "project_id": "d19231fc08ec4bc4829b668040d34512", - "tenant_id": "d19231fc08ec4bc4829b668040d34512" + "tenant_id": "d19231fc08ec4bc4829b668040d34512", + "created_at": "2016-10-10T14:35:34Z", + "description": "", + "ipv6_address_mode": null, + "ipv6_ra_mode": null, + "revision_number": 2, + "service_types": [], + "subnetpool_id": null, + "updated_at": "2016-10-10T14:35:34Z" } ] } diff --git a/api-ref/source/v2/samples/subnets/subnets-list-response.json b/api-ref/source/v2/samples/subnets/subnets-list-response.json index 717c7e498..2eeefa637 100644 --- a/api-ref/source/v2/samples/subnets/subnets-list-response.json +++ b/api-ref/source/v2/samples/subnets/subnets-list-response.json @@ -18,7 +18,15 @@ "ip_version": 4, "gateway_ip": "10.0.0.1", "cidr": "10.0.0.0/24", - "id": "08eae331-0402-425a-923c-34f7cfe39c1b" + "id": "08eae331-0402-425a-923c-34f7cfe39c1b", + "created_at": "2016-10-10T14:35:34Z", + "description": "", + "ipv6_address_mode": null, + "ipv6_ra_mode": null, + "revision_number": 2, + "service_types": [], + "subnetpool_id": null, + "updated_at": "2016-10-10T14:35:34Z" }, { "name": "my_subnet", @@ -38,7 +46,15 @@ "ip_version": 4, "gateway_ip": "192.0.0.1", "cidr": "192.0.0.0/8", - "id": "54d6f61d-db07-451c-9ab3-b9609b6b6f0b" + "id": "54d6f61d-db07-451c-9ab3-b9609b6b6f0b", + "created_at": "2016-10-10T14:35:47Z", + "description": "", + "ipv6_address_mode": null, + "ipv6_ra_mode": null, + "revision_number": 2, + "service_types": [], + "subnetpool_id": null, + "updated_at": "2016-10-10T14:35:47Z" } ] } diff --git a/api-ref/source/v2/subnets.inc b/api-ref/source/v2/subnets.inc index 11c431414..434ecd93a 100644 --- a/api-ref/source/v2/subnets.inc +++ b/api-ref/source/v2/subnets.inc @@ -1,8 +1,4 @@ .. -*- rst -*- -.. needs:method_verification -.. needs:parameter_verification -.. needs:example_verification -.. needs:body_verification ======= Subnets @@ -24,6 +20,12 @@ user has administrative role. You can control which attributes are returned by using the fields query parameter. You can filter results by using query string parameters. +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 @@ -31,6 +33,38 @@ Error response codes: 401 Request ------- +.. rest_parameters:: parameters.yaml + + - fields: fields + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - subnets: subnets-obj + - id: subnet-id-body + - tenant_id: project_id + - project_id: project_id + - name: subnet-name + - enable_dhcp: subnet-enable_dhcp + - network_id: subnet-network_id + - dns_nameservers: subnet-dns_nameservers + - allocation_pools: subnet-allocation_pools + - host_routes: subnet-host_routes + - ip_version: subnet-ip_version + - gateway_ip: subnet-gateway_ip + - cidr: cidr + - created_at: subnet-created_at + - description: subnet-description + - ipv6_address_mode: subnet-ipv6_address_mode + - ipv6_ra_mode: subnet-ipv6_ra_mode + - revision_number: subnet-revision_number + - segment_id: subnet-segment_id + - service_types: subnet-service_types + - subnetpool_id: subnet-subnetpool_id + - updated_at: subnet-updated_at + Response Example ---------------- @@ -80,12 +114,32 @@ subnets must be associated with segments or none of them can be. Neutron enforces this invariant. Currently, routed networks are only supported for provider networks. -Error response codes: 201,404,403,401,400,409 +Normal response codes: 201 + +Error response codes: 404, 403, 401, 400, 409 Request ------- -.. .. rest_parameters:: parameters.yaml +.. rest_parameters:: parameters.yaml + + - subnet: subnet-obj + - tenant_id: project_id-request + - project_id: project_id-request + - name: subnet-name-request + - enable_dhcp: subnet-enable_dhcp-request + - network_id: subnet-network_id + - dns_nameservers: subnet-dns_nameservers-request + - allocation_pools: subnet-allocation_pools-request + - host_routes: subnet-host_routes-request + - ip_version: subnet-ip_version + - gateway_ip: subnet-gateway_ip-request + - cidr: cidr + - description: description-request + - ipv6_address_mode: subnet-ipv6_address_mode-request + - ipv6_ra_mode: subnet-ipv6_ra_mode-request + - segment_id: subnet-segment_id-request + - subnetpool_id: subnet-subnetpool_id-request Request Example --------------- @@ -93,6 +147,40 @@ Request Example .. literalinclude:: samples/subnets/subnet-create-request.json :language: javascript +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - subnet: subnet-obj + - id: subnet-id-body + - tenant_id: project_id + - project_id: project_id + - name: subnet-name + - enable_dhcp: subnet-enable_dhcp + - network_id: subnet-network_id + - dns_nameservers: subnet-dns_nameservers + - allocation_pools: subnet-allocation_pools + - host_routes: subnet-host_routes + - ip_version: subnet-ip_version + - gateway_ip: subnet-gateway_ip + - cidr: cidr + - created_at: subnet-created_at + - description: subnet-description + - ipv6_address_mode: subnet-ipv6_address_mode + - ipv6_ra_mode: subnet-ipv6_ra_mode + - revision_number: subnet-revision_number + - service_types: subnet-service_types + - subnetpool_id: subnet-subnetpool_id + - segment_id: subnet-segment_id + - updated_at: subnet-updated_at + +Response Example +---------------- + +.. literalinclude:: samples/subnets/subnet-create-response.json + :language: javascript + Bulk create subnet ================== @@ -103,12 +191,32 @@ Creates multiple subnets in a single request. Specify a list of subnets in the r The bulk create operation is always atomic. Either all or no subnets in the request body are created. -Error response codes: 201,404,403,401,400,409 +Normal response codes: 201 + +Error response codes: 404, 403, 401, 400, 409 Request ------- -.. .. rest_parameters:: parameters.yaml +.. rest_parameters:: parameters.yaml + + - subnets: subnets-obj + - tenant_id: project_id-request + - project_id: project_id-request + - name: subnet-name-request + - enable_dhcp: subnet-enable_dhcp-request + - network_id: subnet-network_id + - dns_nameservers: subnet-dns_nameservers-request + - allocation_pools: subnet-allocation_pools-request + - host_routes: subnet-host_routes-request + - ip_version: subnet-ip_version + - gateway_ip: subnet-gateway_ip-request + - cidr: cidr + - description: description-request + - ipv6_address_mode: subnet-ipv6_address_mode-request + - ipv6_ra_mode: subnet-ipv6_ra_mode-request + - segment_id: subnet-segment_id-request + - subnetpool_id: subnet-subnetpool_id-request Request Example --------------- @@ -116,6 +224,40 @@ Request Example .. literalinclude:: samples/subnets/subnets-create-bulk-request.json :language: javascript +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - subnets: subnets-obj + - id: subnet-id-body + - tenant_id: project_id + - project_id: project_id + - name: subnet-name + - enable_dhcp: subnet-enable_dhcp + - network_id: subnet-network_id + - dns_nameservers: subnet-dns_nameservers + - allocation_pools: subnet-allocation_pools + - host_routes: subnet-host_routes + - ip_version: subnet-ip_version + - gateway_ip: subnet-gateway_ip + - cidr: cidr + - created_at: subnet-created_at + - description: subnet-description + - ipv6_address_mode: subnet-ipv6_address_mode + - ipv6_ra_mode: subnet-ipv6_ra_mode + - revision_number: subnet-revision_number + - segment_id: subnet-segment_id + - service_types: subnet-service_types + - subnetpool_id: subnet-subnetpool_id + - updated_at: subnet-updated_at + +Response Example +---------------- + +.. literalinclude:: samples/subnets/subnets-create-bulk-response.json + :language: javascript + Show subnet details =================== @@ -134,7 +276,35 @@ Request .. rest_parameters:: parameters.yaml - - subnet_id: subnet_id + - subnet_id: subnet_id-path + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - subnet: subnet-obj + - id: subnet-id-body + - tenant_id: project_id + - project_id: project_id + - created_at: subnet-created_at + - name: subnet-name + - enable_dhcp: subnet-enable_dhcp + - network_id: subnet-network_id + - dns_nameservers: subnet-dns_nameservers + - allocation_pools: subnet-allocation_pools + - host_routes: subnet-host_routes + - ip_version: subnet-ip_version + - gateway_ip: subnet-gateway_ip + - cidr: cidr + - updated_at: subnet-updated_at + - description: subnet-description + - ipv6_address_mode: subnet-ipv6_address_mode + - ipv6_ra_mode: subnet-ipv6_ra_mode + - revision_number: subnet-revision_number + - segment_id: subnet-segment_id + - service_types: subnet-service_types + - subnetpool_id: subnet-subnetpool_id Response Example ---------------- @@ -162,7 +332,13 @@ Request .. rest_parameters:: parameters.yaml - - subnet_id: subnet_id + - subnet_id: subnet_id-path + - name: subnet-name-update-request + - enable_dhcp: subnet-enable_dhcp-request + - dns_nameservers: subnet-dns_nameservers-request + - allocation_pools: subnet-allocation_pools-request + - host_routes: subnet-host_routes-request + - gateway_ip: subnet-gateway_ip-request Request Example --------------- @@ -170,6 +346,34 @@ Request Example .. literalinclude:: samples/subnets/subnet-update-request.json :language: javascript +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - subnet: subnet-obj + - id: subnet-id-body + - tenant_id: project_id + - project_id: project_id + - name: subnet-name + - enable_dhcp: subnet-enable_dhcp + - network_id: subnet-network_id + - dns_nameservers: subnet-dns_nameservers + - allocation_pools: subnet-allocation_pools + - host_routes: subnet-host_routes + - ip_version: subnet-ip_version + - gateway_ip: subnet-gateway_ip + - cidr: cidr + - created_at: subnet-created_at + - description: subnet-description + - ipv6_address_mode: subnet-ipv6_address_mode + - ipv6_ra_mode: subnet-ipv6_ra_mode + - revision_number: subnet-revision_number + - segment_id: subnet-segment_id + - service_types: subnet-service_types + - subnetpool_id: subnet-subnetpool_id + - updated_at: subnet-updated_at + Response Example ---------------- @@ -185,12 +389,19 @@ Deletes a subnet. The operation fails if subnet IP addresses are still allocated. -Error response codes: 409,404,204,401 +Normal response codes: 204 + +Error response codes: 404, 401 Request ------- .. rest_parameters:: parameters.yaml - - subnet_id: subnet_id + - subnet_id: subnet_id-path + +Response +-------- + +There is no body content for the response of a successful DELETE request.