openstack/api-site
Code Issues Proposed changes

Add API Documentation for Vlan Transparency Extension

Browse Source 
* Add API Documentation for Vlan Transparency Extension
* Add json request/response code samples

Closes-Bug: #1433838
Change-Id: I54738116bca046e8e30865d1726d0e7c2527ff3a
This commit is contained in:
Pritesh Kothari 2015-05-07 16:12:24 -07:00 committed by Diane Fleming
parent 9ca8224370
commit 9a2ce8e9af
7 changed files with 227 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
api-ref/src/docbkx/ch_netconn-v2-ext.xml
View File

@ -58,17 +58,17 @@
<para>Enables administrative users to define multiple physical bindings for an OpenStack
Networking network and list or show details for networks with multiple physical
bindings.</para>
<para>You cannot update any <literal>provider</literal> attributes. If you try to do so, an
<para>You cannot update any <code>provider</code> attributes. If you try to do so, an
error occurs.</para>
<para>To delete a network with multiple physical bindings, issue a normal delete network
request.</para>
<para>To define multiple physical bindings for a network, include a
<literal>segments</literal> list in the request body of a <code>POST
/v2.0/networks</code> request. Each element in the <literal>segments</literal> list
<code>segments</code> list in the request body of a <code>POST
/v2.0/networks</code> request. Each element in the <code>segments</code> list
has the same structure as the provider network attributes. These attributes are
<literal>provider:network_type</literal>,
<literal>provider:physical_network</literal>, and
<literal>provider:segmentation_id</literal>. The validation rules for these
<code>provider:network_type</code>,
<code>provider:physical_network</code>, and
<code>provider:segmentation_id</code>. The validation rules for these
attributes are the same as for the <link
xlink:href="http://developer.openstack.org/api-ref-networking-v2.html#network_provider-ext"
>Networks provider extended attributes</link>. You cannot use both extensions at the
@ -78,6 +78,31 @@
<wadl:resources href="../wadls/netconn-api/src/os-networks-multi-provider-ext.wadl"
xmlns:wadl="http://wadl.dev.java.net/2009/02"/>
</section>
<section xml:id="network_vlan_transparency-ext">
<title>VLAN transparency extension (networks)</title>
<para>
Enables plug-ins that support VLAN transparency to deliver
VLAN-transparent trunk networks. If the service does not support VLAN
transparency and a user requests a VLAN-transparent network, the
plug-in refuses to create one and returns an appropriate
error to the user.
</para>
<para>
You cannot update the <code>vlan-transparent</code> attribute. If
you try to do so, an error occurs.
</para>
<para>
To delete a VLAN-transparent network, issue a normal delete
network request.
</para>
<para>
The ML2 plug-in currently supports this extension. With the ML2
plug-in, you can set the <code>vlan-transparent</code> attribute
to either <code>true</code> or <code>false</code>.
</para>
<wadl:resources href="../wadls/netconn-api/src/os-networks-vlan-transparency-ext.wadl"
xmlns:wadl="http://wadl.dev.java.net/2009/02"/>
</section>
<section xml:id="port_binding-ext">
<title>Ports binding extended attributes (ports)</title>
<para>Lists, creates, shows information for, and updates ports.</para>
@ -188,7 +213,7 @@
<tr>
<td>ERROR</td>
<td>Object within the service is not working. Look
for an extra attribute called <literal>error_details</literal>
for an extra attribute called <code>error_details</code>
for a textual explanation on the error, its
cause, and possibly a solution.</td>
</tr>
@ -243,7 +268,7 @@
<tr>
<td>ERROR</td>
<td>Object within the service is not working. Look
for an extra attribute called <literal>error_details</literal>
for an extra attribute called <code>error_details</code>
for a textual explanation on the error, its
cause, and possibly a solution.</td>
</tr>
@ -321,13 +346,13 @@
<section xml:id="extraroute-ext">
<title>Extra routes</title>
<para>Adds extra routes to the
<literal>router</literal> resource.</para>
<code>router</code> resource.</para>
<para>You can update a router to add a set of nexthop IPs and destination
CIDRs.</para>
<note>
<para>The nexthop IP must be a part of a subnet to
which the router interfaces are connected. You can
configure the <literal>routes</literal> attribute on only
configure the <code>routes</code> attribute on only
update operations.</para>
</note>
<wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">

7
api-ref/src/wadls/netconn-api/src/api_samples/network-vlan-transparent-post-req.json Normal file
View File

@ -0,0 +1,7 @@
{
"network": {
"name": "net1",
"admin_state_up": true,
"vlan_transparent": true
}
}

13
api-ref/src/wadls/netconn-api/src/api_samples/network-vlan-transparent-post-resp.json Normal file
View File

@ -0,0 +1,13 @@
{
"network": {
"status": "ACTIVE",
"subnets": [],
"name": "net1",
"admin_state_up": true,
"vlan_transparent": true,
"tenant_id": "5831268f-1f52-49a7-88d5-bc0d7a74d523",
"router:external": false,
"shared": false,
"id": "3114f6e9-f9bc-4570-a941-7329b3b9759f"
}
}

13
api-ref/src/wadls/netconn-api/src/api_samples/networks-vlan-transparent-get-detail-resp.json Normal file
View File

@ -0,0 +1,13 @@
{
"network": {
"status": "ACTIVE",
"subnets": [],
"name": "net1",
"admin_state_up": true,
"tenant_id": "e926fd5a-e9f6-4dc8-8043-a352d974ceaf",
"router:external": false,
"vlan_transparent": true,
"shared": false,
"id": "20403fe9-6c9c-48e5-9edb-c3426a955068"
}
}

28
api-ref/src/wadls/netconn-api/src/api_samples/networks-vlan-transparent-resp.json Normal file
View File

@ -0,0 +1,28 @@
{
"networks": [
{
"status": "ACTIVE",
"subnets": [],
"name": "net1",
"admin_state_up": true,
"tenant_id": "e252a863-92ee-480f-8bd8-71be77089499",
"shared": false,
"router:external": false,
"vlan_transparent": true,
"id": "f5e6d63c-04a4-4b2c-8b27-a9854412d5a7"
},
{
"status": "ACTIVE",
"subnets": [
"3daba37a-bced-4153-a4bb-d83dcc0552d9"
],
"name": "private",
"admin_state_up": true,
"tenant_id": "109e5fae-d976-4791-84c7-6ae0bb3896c3",
"shared": true,
"router:external": false,
"vlan_transparent": false,
"id": "37e11503-3244-49f1-b92a-9f21bab017d9"
}
]
}

9
api-ref/src/wadls/netconn-api/src/common.ent
View File

@ -248,6 +248,15 @@
<para>A <code>segments</code> object that defines one or more
provider segments.</para></wadl:doc>
</param>'>
<!-- VLAN Transparency Attribute Parameters -->
<!ENTITY networkVlanTransparentParameters '
<param xmlns="http://wadl.dev.java.net/2009/02" required="true"
name="vlan_transparent" style="plain" type="xsd:bool">
<wadl:doc xmlns:wadl="http://wadl.dev.java.net/2009/02"
xmlns="http://docbook.org/ns/docbook" xml:lang="EN">
<para>The state of the network, which is VLAN transparent (<code>true</code>)
or not VLAN transparent (<code>false</code>).</para></wadl:doc>
</param>'>
<!ENTITY portListParameters
'<param xmlns="http://wadl.dev.java.net/2009/02" required="true" name="status"
style="plain" type="xsd:string">

122
api-ref/src/wadls/netconn-api/src/os-networks-vlan-transparency-ext.wadl Normal file
View File

@ -0,0 +1,122 @@
<?xml version="1.0" encoding="UTF-8"?>
<!-- (C) 2015 Cisco Systems Inc, All Rights Reserved -->
<!--*******************************************************-->
<!-- Import Common XML Entities -->
<!-- -->
<!-- You can resolve the entities with xmllint -->
<!-- -->
<!-- xmllint -noent os-networks-vlan-transparent-ext.wadl -->
<!--*******************************************************-->
<!DOCTYPE application [
<!ENTITY % common SYSTEM "common.ent">
%common;
<!ENTITY % common_project SYSTEM "../../common_project.ent">
%common_project;
]>
<application xmlns="http://wadl.dev.java.net/2009/02"
xmlns:xsdxt="http://docs.rackspacecloud.com/xsd-ext/v1.0"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:linkend="http://www.w3.org/1999/linkend"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:wadl="http://wadl.dev.java.net/2009/02"
xmlns:csapi="http://docs.openstack.org/compute/api/v1.1">
<!--*******************************************************-->
<!-- All Resources -->
<!--*******************************************************-->
<resources base="https://neutron.example.com/"
xml:id="os-networks-vlan-transparency-ext-v2.0">
<resource id="version" path="//v2.0">
<resource id="Networks" path="networks">
<method href="#listVTNetworks"/>
<method href="#createVTNetwork"/>
<resource path="{network_id}" id="network_id">
<param name="network_id" style="template"
type="csapi:UUID">
<wadl:doc
xmlns="http://docbook.org/ns/docbook"
xml:lang="EN">
<para>
The UUID for the network of interest to
you.
</para>
</wadl:doc>
</param>
<method href="#showVTNetwork"/>
</resource>
</resource>
</resource>
</resources>
<!--*******************************************************-->
<!-- All Methods -->
<!--*******************************************************-->
<method name="GET" id="listVTNetworks">
<wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
title="List networks with VLAN transparency attribute">
<para role="shortdesc">
Lists networks. The response shows the VLAN transparency
attribute.
</para>
</wadl:doc>
<response status="200"> &networkListParameters;
&networkVlanTransparentParameters;
<representation mediaType="application/json">
<wadl:doc xmlns="http://docbook.org/ns/docbook"
xml:lang="EN">
<xsdxt:code
href="api_samples/networks-vlan-transparent-resp.json"
/>
</wadl:doc>
</representation>
</response>
</method>
<method name="POST" id="createVTNetwork">
<wadl:doc xmlns="http://docbook.org/ns/docbook"
title="Create VLAN-transparent network"
xml:lang="EN">
<para role="shortdesc">
Creates a VLAN-transparent network.
</para>
</wadl:doc>
<request> &networkCreateParameters;
&networkVlanTransparentParameters; <representation
mediaType="application/json">
<wadl:doc xmlns="http://docbook.org/ns/docbook"
xml:lang="EN">
<xsdxt:code
href="api_samples/network-vlan-transparent-post-req.json"
/>
</wadl:doc>
</representation>
</request>
<response status="201"> &networkListParameters;
&networkVlanTransparentParameters; <representation
mediaType="application/json">
<wadl:doc xmlns="http://docbook.org/ns/docbook"
xml:lang="EN">
<xsdxt:code
href="api_samples/network-vlan-transparent-post-resp.json"
/>
</wadl:doc>
</representation>
</response>
</method>
<method name="GET" id="showVTNetwork">
<wadl:doc xmlns="http://docbook.org/ns/docbook"
title="Show VLAN-transparent network details">
<para role="shortdesc">
Shows details for a specified VLAN-transparent network.
</para>
</wadl:doc>
<response status="200"> &networkListParameters;
&networkVlanTransparentParameters;
<representation mediaType="application/json">
<wadl:doc xmlns="http://docbook.org/ns/docbook"
xml:lang="EN">
<xsdxt:code
href="api_samples/networks-vlan-transparent-get-detail-resp.json"
/>
</wadl:doc>
</representation>
</response>
</method>
</application>