Add segments to v2 API reference

Change-Id: I0133323412eac1e0ec5a00d4eb018836ce67c88c
Partially-Implements: blueprint routed-networks

api-ref/source/v2/index.rst

@@ -10,6 +10,7 @@ Networking API v2.0
 .. include:: versions.inc
 .. include:: extensions.inc
 .. include:: networks.inc
+.. include:: segments.inc
 .. include:: network-provider.inc
 .. include:: networks-multi-provider-ext.inc
 .. include:: networks-vlan-transparency-ext.inc

api-ref/source/v2/parameters.yaml

@@ -157,6 +157,12 @@ security_group_id_2:
   in: path
   required: false
   type: string
+segment_id-path:
+  description: |
+    The UUID of the segment.
+  in: path
+  required: true
+  type: string
 service_id:
   description: |
     The UUID of the VPN service.
@@ -2150,6 +2156,12 @@ name-request:
   in: body
   required: false
   type: string
+name-segment:
+  description: |
+    Human-readable name of the segment.
+  in: body
+  required: false
+  type: string
 name_1:
   description: |
     A symbolic name for the port.
@@ -2468,6 +2480,14 @@ network_name:
   in: body
   required: true
   type: string
+network_type:
+  description: |
+    The type of physical network that maps to this
+    network resource. For example, ``flat``, ``vlan``, ``vxlan``, or
+    ``gre``.
+  in: body
+  required: true
+  type: string
 networks:
   description: |
     A list of ``network`` objects.
@@ -3423,6 +3443,12 @@ security_groups_2:
   in: body
   required: true
   type: array
+segment_id:
+  description: |
+    The UUID of the segment.
+  in: body
+  required: true
+  type: string
 segments:
   description: |
     A list of provider ``segment`` objects.

api-ref/source/v2/samples/segments/segment-create-request.json

@@ -0,0 +1,8 @@
+{
+    "segment": {
+        "network_id": "5c0cb560-4089-41dd-be29-469907a23b49",
+        "segmentation_id": 2000,
+        "network_type": "vlan",
+        "physical_network": "segment-1"
+    }
+}

api-ref/source/v2/samples/segments/segment-create-response.json

@@ -0,0 +1,11 @@
+{
+  "segment": {
+    "name": null,
+    "network_id": "5c0cb560-4089-41dd-be29-469907a23b49",
+    "segmentation_id": 2000,
+    "network_type": "vlan",
+    "physical_network": "segment-1",
+    "id": "57fe85e4-ca2f-4192-b3cd-d5c249d7a21f",
+    "description": null
+  }
+}

api-ref/source/v2/samples/segments/segment-show-response.json

@@ -0,0 +1,11 @@
+{
+  "segment": {
+    "name": null,
+    "network_id": "5c0cb560-4089-41dd-be29-469907a23b49",
+    "segmentation_id": 2000,
+    "network_type": "vlan",
+    "physical_network": "segment-1",
+    "id": "57fe85e4-ca2f-4192-b3cd-d5c249d7a21f",
+    "description": null
+  }
+}

api-ref/source/v2/samples/segments/segment-update-request.json

@@ -0,0 +1,6 @@
+{
+    "segment": {
+        "name": "1",
+        "description": "Segment One"
+    }
+}

api-ref/source/v2/samples/segments/segment-update-response.json

@@ -0,0 +1,11 @@
+{
+  "segment": {
+    "name": "1",
+    "network_id": "5c0cb560-4089-41dd-be29-469907a23b49",
+    "segmentation_id": 2000,
+    "network_type": "vlan",
+    "physical_network": "segment-1",
+    "id": "57fe85e4-ca2f-4192-b3cd-d5c249d7a21f",
+    "description": "Segment One"
+  }
+}

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

@@ -0,0 +1,22 @@
+{
+  "segments": [
+    {
+      "name": null,
+      "network_id": "5c0cb560-4089-41dd-be29-469907a23b49",
+      "segmentation_id": 2000,
+      "network_type": "vlan",
+      "physical_network": "segment-1",
+      "id": "57fe85e4-ca2f-4192-b3cd-d5c249d7a21f",
+      "description": null
+    },
+    {
+      "name": null,
+      "network_id": "5c0cb560-4089-41dd-be29-469907a23b49",
+      "segmentation_id": 2000,
+      "network_type": "vlan",
+      "physical_network": "segment-2",
+      "id": "f1364c3a-4fc1-4206-b2dc-3254bc25cbfc",
+      "description": null
+    }
+  ]
+}

api-ref/source/v2/samples/subnets/subnet-create-response.json

@@ -3,6 +3,7 @@
         "name": "",
         "enable_dhcp": true,
         "network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
+        "segment_id": null,
         "project_id": "4fd44f30292945e481c7b8a0c8908869",
         "tenant_id": "4fd44f30292945e481c7b8a0c8908869",
         "dns_nameservers": [],

api-ref/source/v2/samples/subnets/subnet-show-response.json

@@ -3,6 +3,7 @@
         "name": "my_subnet",
         "enable_dhcp": true,
         "network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
+        "segment_id": null,
         "project_id": "4fd44f30292945e481c7b8a0c8908869",
         "tenant_id": "4fd44f30292945e481c7b8a0c8908869",
         "created_at": "2016-03-08T20:19:41",

api-ref/source/v2/samples/subnets/subnet-update-response.json

@@ -3,6 +3,7 @@
         "name": "my_subnet",
         "enable_dhcp": true,
         "network_id": "db193ab3-96e3-4cb3-8fc5-05f4296d0324",
+        "segment_id": null,
         "project_id": "26a7980765d0414dbc1fc1f88cdb7e6e",
         "tenant_id": "26a7980765d0414dbc1fc1f88cdb7e6e",
         "dns_nameservers": [],

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

@@ -16,6 +16,7 @@
             "ip_version": 4,
             "name": "",
             "network_id": "e6031bc2-901a-4c66-82da-f4c32ed89406",
+            "segment_id": null,
             "project_id": "d19231fc08ec4bc4829b668040d34512",
             "tenant_id": "d19231fc08ec4bc4829b668040d34512"
         },
@@ -35,6 +36,7 @@
             "ip_version": 4,
             "name": "",
             "network_id": "64239a54-dcc4-4b39-920b-b37c2144effa",
+            "segment_id": null,
             "project_id": "d19231fc08ec4bc4829b668040d34512",
             "tenant_id": "d19231fc08ec4bc4829b668040d34512"
         }

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

@@ -4,6 +4,7 @@
             "name": "private-subnet",
             "enable_dhcp": true,
             "network_id": "db193ab3-96e3-4cb3-8fc5-05f4296d0324",
+            "segment_id": null,
             "project_id": "26a7980765d0414dbc1fc1f88cdb7e6e",
             "tenant_id": "26a7980765d0414dbc1fc1f88cdb7e6e",
             "dns_nameservers": [],
@@ -23,6 +24,7 @@
             "name": "my_subnet",
             "enable_dhcp": true,
             "network_id": "d32019d3-bc6e-4319-9c1d-6722fc136a22",
+            "segment_id": null,
             "project_id": "4fd44f30292945e481c7b8a0c8908869",
             "tenant_id": "4fd44f30292945e481c7b8a0c8908869",
             "dns_nameservers": [],

api-ref/source/v2/segments.inc

@@ -0,0 +1,209 @@
+.. -*- rst -*-
+
+========
+Segments
+========
+
+Lists, shows details for, creates, updates, and deletes segments. The
+segments API is admin-only.
+
+Show segment details
+====================
+
+.. rest_method::  GET /v2.0/segments/{segment_id}
+
+Shows details for a segment.
+
+You can control which response parameters are returned by using the
+fields query parameter. For information, see `Filtering and column
+selection <http://specs.openstack.org/openstack/neutron-
+specs/specs/api/networking_general_api_information.html#filtering-
+and-column-selection>`__.
+
+Normal response codes: 200
+
+Error response codes: 404,401
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - segment_id: segment_id-path
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - id: segment_id
+   - network_id: network_id
+   - physical_network: provider:physical_network
+   - network_type: network_type
+   - segmentation_id: provider:segmentation_id
+   - name: name
+   - description: description
+
+Response Example
+----------------
+
+.. literalinclude:: samples/segments/segment-show-response.json
+   :language: javascript
+
+Update segment
+==============
+
+.. rest_method::  PUT /v2.0/segments/{segment_id}
+
+Updates a segment.
+
+Normal response codes: 200
+
+Error response codes: 404,403,401,400
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - segment_id: segment_id-path
+   - name: name-segment
+   - description: description-request
+
+Request Example
+---------------
+
+.. literalinclude:: samples/segments/segment-update-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - id: segment_id
+   - network_id: network_id
+   - physical_network: provider:physical_network
+   - network_type: network_type
+   - segmentation_id: provider:segmentation_id
+   - name: name
+   - description: description
+
+Response Example
+----------------
+
+.. literalinclude:: samples/segments/segment-update-response.json
+   :language: javascript
+
+Delete segment
+==============
+
+.. rest_method::  DELETE /v2.0/segments/{segment_id}
+
+Deletes a segment and its associated resources.
+
+Normal response codes: 204
+
+Error response codes: 409,404,401
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - segment_id: segment_id-path
+
+Response
+--------
+
+There is no body content for the response of a successful DELETE request.
+
+List segments
+=============
+
+.. rest_method::  GET /v2.0/segments
+
+Lists segments to which the project has access.
+
+Use the ``fields`` query parameter to filter the response. For
+information, see `Filtering and Column Selection <https://wiki.open
+stack.org/wiki/Neutron/APIv2-specification#Filtering_and_Column_Sel
+ection>`__.
+
+Normal response codes: 200
+
+Error response codes: 401
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - fields: fields
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - id: segment_id
+   - network_id: network_id
+   - physical_network: provider:physical_network
+   - network_type: network_type
+   - segmentation_id: provider:segmentation_id
+   - name: name
+   - description: description
+
+Response Example
+----------------
+
+.. literalinclude:: samples/segments/segments-list-response.json
+   :language: javascript
+
+Create segment
+==============
+
+.. rest_method::  POST /v2.0/segments
+
+Creates a segment.
+
+Normal response codes: 201
+
+Error response codes: 401,400
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - network_id: network_id
+   - physical_network: provider:physical_network
+   - network_type: network_type
+   - segmentation_id: provider:segmentation_id
+   - name: name-segment
+   - description: description-request
+
+Request Example
+---------------
+
+.. literalinclude:: samples/segments/segment-create-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - id: segment_id
+   - network_id: network_id
+   - physical_network: provider:physical_network
+   - network_type: network_type
+   - segmentation_id: provider:segmentation_id
+   - name: name
+   - description: description
+
+Response Example
+----------------
+
+.. literalinclude:: samples/segments/segment-create-response.json
+   :language: javascript

api-ref/source/v2/subnets.inc

@@ -72,6 +72,14 @@ to create subnets that support IPv6 configurations, such as
 stateless address autoconfiguration (SLAAC), DHCPv6 stateful, and
 DHCPv6 stateless configurations.
 
+A subnet can optionally be associated with a network segment when
+it is created by specifying the ``segment_id`` of a valid segment
+on the specified network. A network with subnets associated in this
+way is called a routed network. On any given network, all of the
+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
 
 Request
@@ -141,9 +149,9 @@ Update subnet
 
 Updates a subnet.
 
-Some attributes, such as IP version (ip_version), and CIDR (cidr)
-cannot be updated. Attempting to update these attributes results in
-a ``400 Bad Request`` error.
+Some attributes, such as IP version (ip_version), CIDR (cidr), and
+segment (segment_id) cannot be updated. Attempting to update these
+attributes results in a ``400 Bad Request`` error.
 
 Normal response codes: 200