Merge "Add regions resource and calls to Identity API v3"

api-ref/src/docbkx/ch_identity-v3.xml

@@ -8,16 +8,27 @@
     version="5.0-extension RackBook-2.0" xml:id="identity-v3"
     role="api-reference">
     <title>Identity API v3 (CURRENT)</title>
-    <para>Gets an authentication token that permits access to the
-        OpenStack services REST API.</para>
     <para>
+        Gets an authentication token that permits access to the OpenStack
+        services REST API.
+    </para>
+    <para>
+
         Like most OpenStack projects, OpenStack Identity protects its APIs by
-        defining policy rules based on a role-based access control (RBAC) approach.
+        defining policy rules based on a role-based access control (RBAC)
-        These rules are stored in a JSON policy file. The Identity service
+        approach.
-        configuration file, <link xlink:href="http://docs.openstack.org/kilo/config-reference/content/keystone-configuration-file.html"><code>keystone.conf</code></link>, sets the name and
+    </para>
-        location of this policy file. For information about Identity API
+    <para>
-        protection, see <link xlink:href="http://docs.openstack.org/admin-guide-cloud/identity_service_api_protection.html">Identity API protection with role-based access control
+        The Identity service <link
-        (RBAC)</link> in the <citetitle>OpenStack Cloud Administrator Guide</citetitle>.
+        xlink:href="http://docs.openstack.org/kilo/config-reference/content/keystone-configuration-file.html"><code>keystone.conf</code></link>
+        configuration file sets the name and location of a JSON policy file
+        that stores these rules.
+    </para>
+    <para>
+        For information about Identity API protection, see <link
+        xlink:href="http://docs.openstack.org/admin-guide-cloud/identity_service_api_protection.html">Identity
+        API protection with role-based access control (RBAC)</link> in the
+        <citetitle>OpenStack Cloud Administrator Guide</citetitle>.
     </para>
     <section xml:id="versions-identity-v3">
         <title>API versions</title>
@@ -305,4 +316,24 @@
             </wadl:resource>
         </wadl:resources>
     </section>
+    <section xml:id="regions-v3">
+        <title>Regions</title>
+        <para>Manages regions.</para>
+        <para>
+            A region is a general division of an OpenStack deployment.
+            You can associate zero or more sub-regions with a region
+            to create a tree-like structured hierarchy.
+        </para>
+        <para>
+            Although a region does not have a geographical connotation, a
+            deployment can use a geographical name for a region, such as
+            <code>us-east</code>.
+        </para>
+        <wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
+            <!-- create policy -->
+            <wadl:resource href="../wadls/identity-api/src/v3/wadl/identity-admin-v3.wadl#regions"/>
+            <wadl:resource href="../wadls/identity-api/src/v3/wadl/identity-admin-v3.wadl#user_defined_region_id"/>
+            <wadl:resource href="../wadls/identity-api/src/v3/wadl/identity-admin-v3.wadl#region_id"/>
+        </wadl:resources>
+    </section>
 </chapter>

api-ref/src/wadls/identity-api/src/v3/samples/RegionCreateRequest.json

@@ -0,0 +1,6 @@
+{
+    "region": {
+        "description": "US West Subregion 1",
+        "parent_region_id": "829551"
+    }
+}

api-ref/src/wadls/identity-api/src/v3/samples/RegionCreateResponse.json

@@ -0,0 +1,11 @@
+{
+    "region": {
+        "description": "US West Subregion 1",
+        "id": "8ebd7f",
+        "links": {
+            "self": "https://identity:35357/v3/regions/8ebd7f",
+            "child_regions": "https://identity:35357/v3/regions?parent_region_id=8ebd7f"
+        },
+        "parent_region_id": "829551"
+    }
+}

api-ref/src/wadls/identity-api/src/v3/samples/RegionGetResponse.json

@@ -0,0 +1,11 @@
+{
+    "region": {
+        "description": "US Southwest Region",
+        "id": "us-southwest",
+        "links": {
+            "self": "https://identity:35357/v3/regions/us-southwest",
+            "child_regions": "http://identity:35357/v3/regions?parent_region_id=us-southwest"
+        },
+        "parent_region_id": "us-west-coast"
+    }
+}

api-ref/src/wadls/identity-api/src/v3/samples/RegionUpdateRequest.json

@@ -0,0 +1,6 @@
+{
+    "region": {
+        "description": "US Southwest Subregion",
+        "parent_region_id": "us-southwest"
+    }
+}

api-ref/src/wadls/identity-api/src/v3/samples/RegionUpdateResponse.json

@@ -0,0 +1,11 @@
+{
+    "region": {
+        "description": "US Southwest Subregion",
+        "id": "us-southwest-1",
+        "links": {
+            "self": "https://identity:35357/v3/regions/us-southwest-1",
+            "child_regions": "https://identity:35357/v3/regions?parent_region_id=us-southwest-1"
+        },
+        "parent_region_id": "us-southwest"
+    }
+}

api-ref/src/wadls/identity-api/src/v3/samples/RegionsListResponse.json

@@ -0,0 +1,18 @@
+{
+    "regions": [
+        {
+            "description": "US East Region",
+            "id": "us-east",
+            "links": {
+                "self": "https://identity:35357/v3/regions/us-east",
+                "child_regions": "https://identity:35357/v3/regions?parent_region_id=us-east"
+            },
+            "parent_region_id": "us-east-coast"
+        }
+    ],
+    "links": {
+        "self": "https://identity:35357/v3/regions",
+        "previous": null,
+        "next": null
+    }
+}

api-ref/src/wadls/identity-api/src/v3/wadl/common.ent

@@ -415,7 +415,8 @@
                 <code>identity</code> object.</para></wadl:doc>
 </param>'>
 <!ENTITY methodsRequestParam '
-<param name="methods" style="plain" required="true" type="xsd:string" xmlns="http://wadl.dev.java.net/2009/02">
+<param name="methods" style="plain" required="true"
+ type="xsd:string" xmlns="http://wadl.dev.java.net/2009/02">
     <wadl:doc xmlns="http://docbook.org/ns/docbook"
         xmlns:wadl="http://wadl.dev.java.net/2009/02" xml:lang="EN">
         <para>The authentication method, which is
@@ -573,7 +574,7 @@
             disabled.</para></wadl:doc>
 </param>'>
 <!ENTITY idEndpointResponseParam '
-<param name="id" style="plain" required="true" type="xsd:uuid" xmlns="http://wadl.dev.java.net/2009/02">
+<param name="id" style="plain" required="true" type="csapi:uuid" xmlns="http://wadl.dev.java.net/2009/02">
     <wadl:doc xmlns="http://docbook.org/ns/docbook"
         xmlns:wadl="http://wadl.dev.java.net/2009/02" xml:lang="EN"><para>The endpoint ID.</para></wadl:doc>
 </param>'>
@@ -1100,6 +1101,90 @@
         <para>The user password. Required for some authentication back ends.</para>
     </wadl:doc>
 </param>'>
+<!ENTITY regionObjectRequestParam '
+<param name="region" style="plain" type="xsd:string" xmlns="http://wadl.dev.java.net/2009/02"
+    required="true">
+    <wadl:doc xmlns:wadl="http://wadl.dev.java.net/2009/02" xmlns="http://docbook.org/ns/docbook"
+        xml:lang="EN">
+        <para>The <code>region</code> object.</para>
+    </wadl:doc>
+</param>'>
+<!ENTITY regionsObjectRequestParam '
+<param name="regions" style="plain" type="xsd:string" xmlns="http://wadl.dev.java.net/2009/02"
+    required="true">
+    <wadl:doc xmlns:wadl="http://wadl.dev.java.net/2009/02" xmlns="http://docbook.org/ns/docbook"
+        xml:lang="EN">
+        <para>The <code>regions</code> object.</para>
+    </wadl:doc>
+</param>'>
+<!ENTITY region_descriptionRequestParam '
+<param name="description" style="plain" type="xsd:string" xmlns="http://wadl.dev.java.net/2009/02"
+    required="false">
+    <wadl:doc xmlns:wadl="http://wadl.dev.java.net/2009/02" xmlns="http://docbook.org/ns/docbook"
+        xml:lang="EN">
+        <para>The region description.</para>
+    </wadl:doc>
+</param>'>
+<!ENTITY parent_region_idRequestParam '
+<param name="parent_region_id" style="plain" type="xsd:string" xmlns="http://wadl.dev.java.net/2009/02"
+    required="false">
+    <wadl:doc xmlns:wadl="http://wadl.dev.java.net/2009/02" xmlns="http://docbook.org/ns/docbook"
+        xml:lang="EN">
+        <para>
+            If the region is hierarchically a child of another region, set
+            this parameter to the ID of the parent region.
+        </para>
+    </wadl:doc>
+</param>'>
+<!ENTITY RegionsResponseParams '
+<param name="description" style="plain" type="xsd:string" xmlns="http://wadl.dev.java.net/2009/02"
+    required="true">
+    <wadl:doc xmlns:wadl="http://wadl.dev.java.net/2009/02" xmlns="http://docbook.org/ns/docbook"
+        xml:lang="EN">
+        <para>The region description.</para>
+    </wadl:doc>
+</param>
+<param name="id" style="plain" type="xsd:string" xmlns="http://wadl.dev.java.net/2009/02"
+    required="true">
+    <wadl:doc xmlns:wadl="http://wadl.dev.java.net/2009/02" xmlns="http://docbook.org/ns/docbook"
+        xml:lang="EN">
+        <para>
+            The ID for the region.
+        </para>
+    </wadl:doc>
+</param>
+<param name="links" style="plain" type="xsd:string"
+    xmlns="http://wadl.dev.java.net/2009/02" required="true">
+    <wadl:doc xmlns:wadl="http://wadl.dev.java.net/2009/02"
+        xmlns="http://docbook.org/ns/docbook" xml:lang="EN"><para>The
+         links for the region.</para></wadl:doc>
+</param>
+<param name="parent_region_id" style="plain" type="xsd:string" xmlns="http://wadl.dev.java.net/2009/02"
+    required="true">
+    <wadl:doc xmlns:wadl="http://wadl.dev.java.net/2009/02" xmlns="http://docbook.org/ns/docbook"
+        xml:lang="EN">
+        <para>
+            The ID for the parent region.
+        </para>
+    </wadl:doc>
+</param>'>
+<!ENTITY parent_region_idQueryParam '
+<param name="parent_region_id" style="query" type="xsd:string" xmlns="http://wadl.dev.java.net/2009/02"
+    required="false">
+    <wadl:doc xmlns:wadl="http://wadl.dev.java.net/2009/02" xmlns="http://docbook.org/ns/docbook"
+        xml:lang="EN">
+        <para>
+            Filters the results by the specified parent region, by ID.
+        </para>
+    </wadl:doc>
+</param>'>
+<!ENTITY RegionLinksResponseParam '
+<param name="links" style="plain" type="xsd:string"
+    xmlns="http://wadl.dev.java.net/2009/02" required="true">
+    <wadl:doc xmlns:wadl="http://wadl.dev.java.net/2009/02"
+        xmlns="http://docbook.org/ns/docbook" xml:lang="EN"><para>The
+             links for the regions resource.</para></wadl:doc>
+</param>'>
 <!-- Useful for describing APIs -->
 <!ENTITY GET    '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
 <!ENTITY PUT    '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>