Update Networking API and extensions

- Put extensions in alphabetical order
- Fix broken links in Identity API
- Rename netconn* files to networking* to match service name

Change-Id: I44e600e5e75292b70f875d82e73fb903fb77bb1f
Closes-Bug: #1529421

api-ref-guides/src/bk-api-ref-networking-v2.xml

@@ -35,6 +35,6 @@
             </annotation>
         </legalnotice>
     </info>
-    <xi:include href="../../api-ref/src/docbkx/ch_netconn-v2.xml"/>
+    <xi:include href="../../api-ref/src/docbkx/ch_networking-v2.xml"/>
-    <xi:include href="../../api-ref/src/docbkx/ch_netconn-v2-ext.xml"/>
+    <xi:include href="../../api-ref/src/docbkx/ch_networking-v2-ext.xml"/>
 </book>

api-ref-guides/src/bk-api-ref.xml

@@ -45,8 +45,8 @@
     <xi:include href="../../api-ref/src/docbkx/ch_identity-v2-ext.xml"/>
     <xi:include href="../../api-ref/src/docbkx/ch_images-v2.xml"/>
     <xi:include href="../../api-ref/src/docbkx/ch_images-v1.xml"/>
-    <xi:include href="../../api-ref/src/docbkx/ch_netconn-v2.xml"/>
+    <xi:include href="../../api-ref/src/docbkx/ch_networking-v2.xml"/>
-    <xi:include href="../../api-ref/src/docbkx/ch_netconn-v2-ext.xml"/>
+    <xi:include href="../../api-ref/src/docbkx/ch_networking-v2-ext.xml"/>
     <xi:include href="../../api-ref/src/docbkx/ch_objectstorage-v1.xml"/>
     <xi:include href="../../api-ref/src/docbkx/ch_orchestration-v1.xml"/>
     <xi:include href="../../api-ref/src/docbkx/ch_share-v2.xml"/>

api-ref/src/docbkx/api-ref-networking-v2-ext.xml

@@ -19,5 +19,5 @@
       <xi:include href="itemizedlist-service-list.xml"/>
     </annotation>
   </info>
-  <xi:include href="ch_netconn-v2-ext.xml"/>
+  <xi:include href="ch_networking-v2-ext.xml"/>
 </book>

api-ref/src/docbkx/api-ref-networking-v2.xml

@@ -19,5 +19,5 @@
       <xi:include href="itemizedlist-service-list.xml"/>
     </annotation>
   </info>
-  <xi:include href="ch_netconn-v2.xml"/>
+  <xi:include href="ch_networking-v2.xml"/>
 </book>

api-ref/src/docbkx/ch_images-v1.xml

@@ -5,7 +5,7 @@
     xmlns:linkend="http://www.w3.org/1999/linkend"
     xmlns:xref="http://www.w3.org/1999/xref"
     xmlns:wadl="http://wadl.dev.java.net/2009/02"
-    version="5.0-extension RackBook-2.0" xml:id="images-api-v1"
+    version="5.0-extension RackBook-2.0" xml:id="images-v1"
     role="api-reference">
     <title>Image service API v1 (SUPPORTED)</title>
     <para>Loads images for use at launch time by the Compute API. Also,
@@ -36,7 +36,7 @@
             </wadl:resource>-->
         </wadl:resources>
     </section>
-    <section xml:id="images-v1">
+    <section xml:id="images-images-v1">
         <title>Images</title>
         <wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
             <wadl:resource href="../wadls/image-api/src/v1/wadl/images-v1.wadl#Images">

api-ref/src/docbkx/ch_images-v2.xml

@@ -5,7 +5,7 @@
     xmlns:linkend="http://www.w3.org/1999/linkend"
     xmlns:xref="http://www.w3.org/1999/xref"
     xmlns:wadl="http://wadl.dev.java.net/2009/02"
-    version="5.0-extension RackBook-2.0" xml:id="images-api-v2"
+    version="5.0-extension RackBook-2.0" xml:id="images-v2"
     role="api-reference">
     <title>Image service API v2 (CURRENT)</title>
     <para>Image service API v2.0, API v2.1, API v2.2, and API v2.3.</para>
@@ -24,7 +24,7 @@
             </wadl:resource>
         </wadl:resources>
     </section>
-    <section xml:id="images-v2">
+    <section xml:id="images-images-v2">
         <title>Images</title>
         <para>Creates, lists, updates, and deletes images.</para>
         <para>

api-ref/src/docbkx/ch_networking-v2-ext.xml

@@ -9,7 +9,7 @@
     xmlns:linkend="http://www.w3.org/1999/linkend"
     xmlns:xref="http://www.w3.org/1999/xref"
     xmlns:wadl="http://wadl.dev.java.net/2009/02"
-    version="5.0-extension RackBook-2.0" xml:id="netconn-v2-ext"
+    version="5.0-extension RackBook-2.0" xml:id="networking-v2-ext"
     role="api-reference">
     <title>Networking API v2.0 extensions (CURRENT)</title>
     <section xml:id="neutron_extensions">
@@ -19,19 +19,19 @@
             extension.
         </para>
         <wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
-            <wadl:resource href="../wadls/netconn-api/src/wadl/networks.wadl#extensions">
+            <wadl:resource href="../wadls/networking-api/src/wadl/networks.wadl#extensions">
                 <wadl:method href="#listExtensions"/>
             </wadl:resource>
-            <wadl:resource href="../wadls/netconn-api/src/wadl/networks.wadl#extension">
+            <wadl:resource href="../wadls/networking-api/src/wadl/networks.wadl#extension">
                 <wadl:method href="#showExtension"/>
             </wadl:resource>
         </wadl:resources>
     </section>
     <section xml:id="fwaas-v2.0">
-        <title>FWaaS v2.0 (CURRENT) (firewalls)</title>
+        <title>FWaaS v2.0 (CURRENT) (fw, firewalls, firewall_policies, firewall_rules)</title>
         <para>
-            The Firewall-as-a-Service (FWaaS) v2.0 extension enables you to
+            Use the Firewall-as-a-Service (FWaaS) v2.0 extension to deploy
-            deploy firewalls to protect your networks.
+            firewalls to protect your networks.
         </para>
         <para>
             The FWaaS extension enables you to:
@@ -42,8 +42,9 @@
                     tenant networks.</para>
             </listitem>
             <listitem>
-                <para>Apply TCP, UDP, ICMP, or protocol-agnostic
+                <para>
-                rules.</para>
+                    Apply TCP, UDP, ICMP, or protocol-agnostic rules.
+                </para>
             </listitem>
             <listitem>
                 <para>
@@ -83,44 +84,17 @@
                 </para>
             </listitem>
         </itemizedlist>
-        <wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
+        <wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02"
-            <wadl:resource href="../wadls/netconn-api/src/wadl/firewalls.wadl#firewalls">
+            href="../wadls/networking-api/src/wadl/firewalls.wadl"/>
-                <wadl:method href="#listFirewalls"/>
-                <wadl:method href="#createFirewall"/>
-            </wadl:resource>
-            <wadl:resource href="../wadls/netconn-api/src/wadl/firewalls.wadl#firewall_id">
-                <wadl:method href="#showFirewall"/>
-                <wadl:method href="#updateFirewall"/>
-                <wadl:method href="#deleteFirewall"/>
-            </wadl:resource>
-           <!--  <wadl:resource href="../wadls/netconn-api/src/wadl/fwaasv2.0.wadl#FirewallPolicies">
-                <wadl:method href="#listFirewallPolicies"/>
-                <wadl:method href="#createFirewallPolicy"/>
-            </wadl:resource>
-            <wadl:resource href="../wadls/netconn-api/src/wadl/fwaasv2.0.wadl#firewallpolicy_id">
-                <wadl:method href="#showFirewallPolicy"/>
-                <wadl:method href="#updateFirewallPolicy"/>
-                <wadl:method href="#deleteFirewallPolicy"/>
-            </wadl:resource>
-            <wadl:resource href="../wadls/netconn-api/src/wadl/fwaasv2.0.wadl#FirewallRules">
-                <wadl:method href="#listFirewallRules"/>
-                <wadl:method href="#createFirewallRule"/>
-            </wadl:resource>
-            <wadl:resource href="../wadls/netconn-api/src/wadl/fwaasv2.0.wadl#firewall_rule_id">
-                <wadl:method href="#showFirewallRule"/>
-                <wadl:method href="#updateFirewallRule"/>
-                <wadl:method href="#deleteFirewallRule"/>
-            </wadl:resource> -->
-        </wadl:resources>
     </section>
      <section xml:id="lbaas-v2.0">
         <title>LBaaS 2.0 (STABLE) (lbaas, loadbalancers, listeners, health_monitors, pools, members)</title>
         <para>
-            The Load-Balancer-as-a-Service (LBaaS) version 2.0 extension pairs with the Networking 2.0 API
+            The Load-Balancer-as-a-Service (LBaaS) version 2.0 extension pairs
-            to enable OpenStack tenants to manage load balancers for their
+            with the Networking 2.0 API to enable OpenStack tenants to manage
-            VMs. With this extension you can load-balance client traffic from
+            load balancers for their VMs. With this extension you can load-
-            one network to application services, such as VMs, on the same
+            balance client traffic from one network to application services,
-            network.
+            such as VMs, on the same network.
         </para>
         <para>
             Use this extension to create and manage load balancers, listeners,
@@ -170,15 +144,16 @@
         </table>
         <para></para>
         <wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02"
-            href="../wadls/netconn-api/src/wadl/lbaas-v2.0.wadl"/>
+            href="../wadls/networking-api/src/wadl/lbaas-v2.0.wadl"/>
     </section>
     <section xml:id="lbaas-v1.0">
         <title>LBaaS 1.0 (DEPRECATED) (lb, vips, health_monitors, pools, members)</title>
         <para>
-            The Load-Balancer-as-a-Service (LBaaS) v1.0 extension pairs with the Networking v2.0 API to
+            The Load-Balancer-as-a-Service (LBaaS) v1.0 extension pairs with
-            enable OpenStack tenants to manage load balancers for their VMs.
+            the Networking v2.0 API to enable OpenStack tenants to manage load
-            With this extension, you can load-balance client traffic from one
+            balancers for their VMs. With this extension, you can load-balance
-            network to application services, such as VMs, on the same network.
+            client traffic from one network to application services, such as
+            VMs, on the same network.
         </para>
         <para>
             Use this extension to create and manage virtual IP addresses
@@ -230,14 +205,14 @@
         </table>
         <para></para>
         <wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02"
-            href="../wadls/netconn-api/src/wadl/lbaas-v1.0.wadl"
+            href="../wadls/networking-api/src/wadl/lbaas-v1.0.wadl"
         > </wadl:resources>
     </section>
     <section xml:id="metering-labels-ext" xmlns:wadl="http://wadl.dev.java.net/2009/02">
         <title>Metering labels and rules (metering-labels, metering-label-rules)</title>
         <para>Creates, modifies, and deletes OpenStack Layer3 metering labels and rules.</para>
         <wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02"
-            href="../wadls/netconn-api/src/wadl/metering-labels.wadl"/>
+            href="../wadls/networking-api/src/wadl/metering-labels.wadl"/>
     </section>
     <section xml:id="network_provider-ext">
         <title>Networks provider extended attributes (networks)</title>
@@ -255,7 +230,7 @@
             same time.
         </para>
         <wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02"
-            href="../wadls/netconn-api/src/wadl/networks-provider.wadl"/>
+            href="../wadls/networking-api/src/wadl/networks-provider.wadl"/>
     </section>
     <section xml:id="networks-multi-provider-ext">
         <title>Networks multiple provider extension (networks)</title>
@@ -291,7 +266,7 @@
             plug-in, you can specify multiple VLANs for a network, a VXLAN
             tunnel ID, and a VLAN.
         </para>
-        <wadl:resources href="../wadls/netconn-api/src/wadl/networks-multi-provider.wadl"
+        <wadl:resources href="../wadls/networking-api/src/wadl/networks-multi-provider.wadl"
             xmlns:wadl="http://wadl.dev.java.net/2009/02"/>
     </section>
     <section xml:id="networks-vlan-transparency-ext">
@@ -316,7 +291,7 @@
             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/wadl/networks-vlan-transparency.wadl"
+        <wadl:resources href="../wadls/networking-api/src/wadl/networks-vlan-transparency.wadl"
             xmlns:wadl="http://wadl.dev.java.net/2009/02"/>
     </section>
     <section xml:id="port_binding-ext">
@@ -325,11 +300,11 @@
             Lists, creates, shows information for, updates, and deletes ports.
         </para>
         <wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
-            <wadl:resource href="../wadls/netconn-api/src/wadl/ports-binding.wadl#ports">
+            <wadl:resource href="../wadls/networking-api/src/wadl/ports-binding.wadl#ports">
                 <wadl:method href="#listPorts"/>
                 <wadl:method href="#createPort"/>
             </wadl:resource>
-            <wadl:resource href="../wadls/netconn-api/src/wadl/ports-binding.wadl#port_id">
+            <wadl:resource href="../wadls/networking-api/src/wadl/ports-binding.wadl#port_id">
                 <wadl:method href="#showPort"/>
                 <wadl:method href="#updatePort"/>
                 <wadl:method href="#deletePort"/>
@@ -346,7 +321,7 @@
             A quota value of <code>-1</code> means that quota has no limit.
         </para>
         <wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02"
-            href="../wadls/netconn-api/src/wadl/quotas.wadl"/>
+            href="../wadls/networking-api/src/wadl/quotas.wadl"/>
     </section>
     <section xml:id="extraroute-ext">
         <title>Extra routes (routers)</title>
@@ -362,7 +337,7 @@
             </para>
         </note>
         <wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
-            <wadl:resource href="../wadls/netconn-api/src/wadl/routers.wadl#router_id">
+            <wadl:resource href="../wadls/networking-api/src/wadl/routers.wadl#router_id">
                 <wadl:method href="#updateExtraRoutes"/>
             </wadl:resource>
         </wadl:resources>
@@ -393,7 +368,7 @@
             </listitem>
         </itemizedlist>
         <wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02"
-            href="../wadls/netconn-api/src/wadl/layer3.wadl"/>
+            href="../wadls/networking-api/src/wadl/layer3.wadl"/>
     </section>
     <section xml:id="security_groups">
         <title>Security groups (security-groups)</title>
@@ -402,18 +377,18 @@
             security groups.
         </para>
         <wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
-            <wadl:resource href="../wadls/netconn-api/src/wadl/security-groups.wadl#security_groups">
+            <wadl:resource href="../wadls/networking-api/src/wadl/security-groups.wadl#security_groups">
                 <wadl:method href="#listSecGroups"/>
                 <wadl:method href="#createSecGroup"/>
             </wadl:resource>
-            <wadl:resource href="../wadls/netconn-api/src/wadl/security-groups.wadl#security_group_id">
+            <wadl:resource href="../wadls/networking-api/src/wadl/security-groups.wadl#security_group_id">
                 <wadl:method href="#showSecGroup"/>
                 <wadl:method href="#updateSecGroup"/>
                 <wadl:method href="#deleteSecGroup"/>
             </wadl:resource>
         </wadl:resources>
     </section>
-    <!-- <section xml:id="netconn-security_group-rules">
+    <!-- <section xml:id="networking-security_group-rules">
         <title>Security group rules (security-group-rules)</title>
         <para>
             Lists, creates, shows information for, and deletes security group
@@ -421,12 +396,12 @@
         </para>
         <wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
             <wadl:resource
-                href="../wadls/netconn-api/src/wadl/security-groups.wadl#security_groups_rules">
+                href="../wadls/networking-api/src/wadl/security-groups.wadl#security_groups_rules">
                 <wadl:method href="#listSecGroupRules"/>
                 <wadl:method href="#createSecGroupRule"/>
             </wadl:resource>
             <wadl:resource
-                href="../wadls/netconn-api/src/wadl/security-groups.wadl#rules-security-groups-id">
+                href="../wadls/networking-api/src/wadl/security-groups.wadl#rules-security-groups-id">
                 <wadl:method href="#showSecGroupRule"/>
                 <wadl:method href="#deleteSecGroupRule"/>
             </wadl:resource>
@@ -438,11 +413,11 @@
             Lists, creates, shows details for, updates, and deletes subnet pools.
         </para>
         <wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
-            <wadl:resource href="../wadls/netconn-api/src/wadl/subnet-pools.wadl#SubnetPools">
+            <wadl:resource href="../wadls/networking-api/src/wadl/subnet-pools.wadl#SubnetPools">
                 <wadl:method href="#listSubnetPools"/>
                 <wadl:method href="#createSubnetPool"/>
             </wadl:resource>
-            <wadl:resource href="../wadls/netconn-api/src/wadl/subnet-pools.wadl#subnetpool_id">
+            <wadl:resource href="../wadls/networking-api/src/wadl/subnet-pools.wadl#subnetpool_id">
                 <wadl:method href="#showSubnetPool"/>
                 <wadl:method href="#updateSubnetPool"/>
                 <wadl:method href="#removeSubnetPool"/>
@@ -515,7 +490,7 @@
             </listitem>
         </itemizedlist>
          <wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02"
-            href="../wadls/netconn-api/src/wadl/vpnaas-v2.0.wadl"
+            href="../wadls/networking-api/src/wadl/vpnaas-v2.0.wadl"
         > </wadl:resources>
     </section>
 </chapter>

api-ref/src/docbkx/ch_networking-v2.xml

@@ -5,7 +5,7 @@
     xmlns:linkend="http://www.w3.org/1999/linkend"
     xmlns:xref="http://www.w3.org/1999/xref"
     xmlns:wadl="http://wadl.dev.java.net/2009/02"
-    version="5.0-extension RackBook-2.0" xml:id="netconn-v2"
+    version="5.0-extension RackBook-2.0" xml:id="networking-v2"
     role="api-reference">
     <title>Networking API v2.0 (CURRENT)</title>
     <para>
@@ -25,31 +25,28 @@
     <section xml:id="versions-networks-v2">
         <title>API versions</title>
         <para>
-            Lists information for all Networking API versions and shows
+            Lists information for all Networking API versions.
-            details about API v2.0.
         </para>
         <wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
-            <wadl:resource href="../wadls/netconn-api/src/wadl/networks.wadl#networks-versions">
+            <wadl:resource href="../wadls/networking-api/src/wadl/networks.wadl#networks-versions">
                 <wadl:method href="#networks-listVersions"/>
             </wadl:resource>
-            <wadl:resource href="../wadls/netconn-api/src/wadl/networks.wadl#networks-version">
-                <wadl:method href="#networks-versionDetails"/>
-            </wadl:resource>
         </wadl:resources>
     </section>
     <section xml:id="networks">
         <title>Networks</title>
-        <para>Lists, shows information for, creates, updates, and deletes
+        <para>
-            networks.</para>
+            Lists, shows details for, creates, updates, and deletes networks.
+        </para>
         <wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
             <wadl:resource
-                href="../wadls/netconn-api/src/wadl/networks.wadl#networks">
+                href="../wadls/networking-api/src/wadl/networks.wadl#networks">
                 <wadl:method href="#listNetworks"/>
                 <wadl:method href="#createNetwork"/>
                 <wadl:method href="#bulkCreateNetwork"/>
             </wadl:resource>
             <wadl:resource
-                href="../wadls/netconn-api/src/wadl/networks.wadl#network_id">
+                href="../wadls/networking-api/src/wadl/networks.wadl#network_id">
                 <wadl:method href="#showNetwork"/>
                 <wadl:method href="#updateNetwork"/>
                 <wadl:method href="#deleteNetwork"/>
@@ -59,23 +56,26 @@
     <section xml:id="subnets">
         <title>Subnets</title>
         <para>
-            Lists, shows information for, creates, updates, and deletes subnet
+            Lists, shows details for, creates, updates, and deletes subnet
             resources.
         </para>
-        <wadl:resources href="../wadls/netconn-api/src/wadl/subnets.wadl"
+        <wadl:resources href="../wadls/networking-api/src/wadl/subnets.wadl"
             xmlns:wadl="http://wadl.dev.java.net/2009/02"/>
     </section>
     <section xml:id="ports">
         <title>Ports</title>
-        <para>Lists, shows information for, creates, updates, and deletes
+        <para>
-            ports.</para>
+            Lists, shows details for, creates, updates, and deletes ports.
-        <wadl:resources href="../wadls/netconn-api/src/wadl/ports.wadl"
+        </para>
+        <wadl:resources href="../wadls/networking-api/src/wadl/ports.wadl"
             xmlns:wadl="http://wadl.dev.java.net/2009/02"/>
     </section>
     <section xml:id="service-type">
         <title>Service providers</title>
-        <para>Lists service providers.</para>
+        <para>
-        <wadl:resources href="../wadls/netconn-api/src/wadl/service-providers.wadl"
+            Lists service providers.
+        </para>
+        <wadl:resources href="../wadls/networking-api/src/wadl/service-providers.wadl"
             xmlns:wadl="http://wadl.dev.java.net/2009/02"/>
     </section>
 </chapter>

api-ref/src/docbkx/ch_share-v1.xml

@@ -10,7 +10,7 @@
    xmlns:xref="http://www.w3.org/1999/xref"
    xmlns:wadl="http://wadl.dev.java.net/2009/02"
    version="5.0-extension RackBook-2.0"
-   xml:id="share-api-v1">
+   xml:id="share-v1">
   <title>Shared File Systems API v1 (SUPPORTED)</title>
   <para>
     Provides coordinated access to shared or distributed file systems.

api-ref/src/docbkx/ch_share-v2-experimental.xml

@@ -10,7 +10,7 @@
    xmlns:xref="http://www.w3.org/1999/xref"
    xmlns:wadl="http://wadl.dev.java.net/2009/02"
    version="5.0-extension RackBook-2.0"
-   xml:id="share-api-v2-experimental"
+   xml:id="share-v2-experimental"
    role="api-reference">
     <title>Shared File Systems API v2 (EXPERIMENTAL)</title>
     <para>

api-ref/src/docbkx/ch_share-v2.xml

@@ -10,7 +10,7 @@
    xmlns:xref="http://www.w3.org/1999/xref"
    xmlns:wadl="http://wadl.dev.java.net/2009/02"
    version="5.0-extension RackBook-2.0"
-   xml:id="share-api-v2"
+   xml:id="share-v2"
    role="api-reference">
     <title>Shared File Systems API v2 (CURRENT)</title>
     <para>

api-ref/src/docbkx/preface.xml

@@ -15,22 +15,21 @@
     </para>
     <para>
         The API <emphasis role="bold">status</emphasis> reflects the state of
-        the endpoint on the service. <emphasis role="bold"
+        the endpoint on the service. <emphasis role="bold">CURRENT</emphasis>
-        >CURRENT</emphasis> is a stable version that is up-to-date, recent,
+        is a stable version that is up-to-date, recent, and might receive
-        and might receive future versions. This endpoint should be prioritized
+        future versions. This endpoint should be prioritized over all others.
-        over all others. <emphasis role="bold">SUPPORTED</emphasis> is a
+        <emphasis role="bold">SUPPORTED</emphasis> is a stable version that is
-        stable version that is available on the server. However, it is not
+        available on the server. However, it is not likely the most recent
-        likely the most recent available and might not be updated or might be
+        available and might not be updated or might be deprecated at some time
-        deprecated at some time in the future. <emphasis role="bold"
+        in the future. <emphasis role="bold" >DEPRECATED</emphasis> is a
-        >DEPRECATED</emphasis> is a stable version that is still available but
+        stable version that is still available but is being deprecated and
-        is being deprecated and might be removed in the future. <emphasis
+        might be removed in the future. <emphasis role="bold">EXPERIMENTAL</emphasis>
-        role="bold">EXPERIMENTAL</emphasis> is not a stable version. This
+        is not a stable version. This version is under development or contains
-        version is under development or contains features that are otherwise
+        features that are otherwise subject to change. For more information
-        subject to change. For more information about API <emphasis
+        about API <emphasis role="bold">status</emphasis> values and version
-        role="bold">status</emphasis> values and version information, see
+        information, see <link
-        <link
+        xlink:href="https://wiki.openstack.org/wiki/VersionDiscovery">Version
-        xlink:href="https://wiki.openstack.org/wiki/VersionDiscovery"
+        Discovery</link>.
-        >Version Discovery</link>.
     </para>
     <para>
         You must install the packages for each API separately.
@@ -44,22 +43,23 @@
     </para>
     <para>
         The body of an authentication request must include a payload that
-        specifies the authentication method, which is
+        specifies the authentication method, which is <code>password</code> or
-        <code>password</code> or <code>token</code>, the credentials, and,
+        <code>token</code>, the credentials, and, optionally, the
-        optionally, the authorization scope. You can scope a token to a
+        authorization scope. You can scope a token to a project or domain, or
-        project or domain, or the token can be unscoped. You cannot scope
+        the token can be unscoped. You cannot scope a token to both a project
-        a token to both a project and domain.
+        and domain.
     </para>
     <wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
         <wadl:resource href="../wadls/identity-api/src/v3/wadl/identity-admin-v3.wadl#tokens">
             <wadl:method href="#authenticatePasswordUnscoped"/>
-            <wadl:method href="#authenticatePasswordExplicitUnscoped"/>
             <wadl:method href="#authenticatePasswordScoped"/>
+            <wadl:method href="#authenticatePasswordExplicitUnscoped"/>
             <wadl:method href="#authenticateTokenUnscoped"/>
             <wadl:method href="#authenticateTokenScoped"/>
         </wadl:resource>
     </wadl:resources>
-    <para>To get started with the APIs, see the <link
+    <para>
-            xlink:href="http://developer.openstack.org/api-guide/quick-start/"
+        To get started with the APIs, see the <link
-            >OpenStack API Guide</link>.</para>
+        xlink:href="http://docs.openstack.org/api/quick-start/content/">OpenStack API Quick Start</link>.
+    </para>
 </preface>