Adding initial document for OS-KSADM-admin extension.Related changes on wadl,json,xsd etc.

Change-Id: Id95c35e189f992926e08d3e486361d65929f7dcc

12 files changed, 242 insertions, 46 deletions

diff --git a/keystone/content/admin/OS-KSADM-admin.wadl b/keystone/content/admin/OS-KSADM-admin.wadl
index 2e6a1000..8e484d0b 100644
--- a/keystone/content/admin/OS-KSADM-admin.wadl
+++ b/keystone/content/admin/OS-KSADM-admin.wadl
@@ -62,12 +62,13 @@
                         <resource id="userCredentials" path="credentials">
                             <method href="#addUserCredential"/>
                             <method href="#listCredentials"/>
-                            <resource id="userCredentialsByType" path="{credentialType}">
+                            <resource id="userCredentialsByType" path="{credential-type}">
                                 <method href="#listCredentialsByType"/>
                             </resource>
-                            <resource id="userCredentialByTypeAndId" path="{credentialTypeAndId}">
+                            <resource id="userCredentialByTypeAndId" path="{credential-type-and-id}">
                                 <param name="credentialTypeAndId" style="template" type="xsd:string"/>
                                 <method href="#updateUserCredential"/>
+                                <method href="#deleteUserCredential"/>
                                 <method href="#getUserCredential"/>
                             </resource>
                         </resource>
@@ -106,9 +107,9 @@
             <resource id="role-service-OS-KSADM" path="OS-KSADM">
                 <resource id="roles" path="roles">
                     <method href="#listRoles"/>
+                    <method href="#addRole"/>
                     <resource id="roleId" path="{roleId}">
                         <param name="roleId" style="template" type="xsd:string"/>
-                        <method href="#addRole"/>
                         <method href="#getRole"/>
                         <method href="#deleteRole"/>
                     </resource>
@@ -132,25 +133,20 @@
     <!--*******************************************************-->
 
     <!-- Tenant Operations -->
-    <method name="GET" id="listTenants">
-        <doc xml:lang="EN" title="List Tenants">
-            <p xmlns="http://www.w3.org/1999/xhtml">Lists all tenants.</p>
-        </doc>
-        <request>
-            <param name="marker" style="query" required="false" type="xsd:string"/>
-            <param name="limit" style="query" required="false" type="xsd:int"/>
-        </request>
-        <response status="200 203">
-            <representation mediaType="application/xml" element="identity:tenants"/>
-            <representation mediaType="application/json"/>
-        </response>
-        &commonFaults;
-        &getFaults;
-    </method>
-    
     <method name="POST" id="addTenant">
-        <doc xml:lang="EN" title="Create a Tenant">
-            <p xmlns="http://www.w3.org/1999/xhtml">Creates a tenant.</p>
+        <doc xml:lang="EN" title="Add Tenant">
+            <p xmlns="http://www.w3.org/1999/xhtml" class="shortdesc">
+                Creates a tenant.
+            </p>
+            <p xmlns="http://www.w3.org/1999/xhtml">This call creates a tenant.</p>
+            <examples xmlns="http://docs.rackspace.com/api" title="Tenant Creation Request">
+                <example href="../common/samples/tenantwithoutid.xml" language="xml"/>
+                <example href="../common/samples/tenantwithoutid.json" language="javascript"/>
+            </examples>
+            <examples xmlns="http://docs.rackspace.com/api" title="Tenant Creation Response">
+                <example href="../common/samples/tenant.xml" language="xml"/>
+                <example href="../common/samples/tenant.json" language="javascript"/>
+            </examples>            
         </doc>
         <request>
             <representation mediaType="application/xml" element="identity:tenant"/>
@@ -164,9 +160,20 @@
         &postPutFaults;
     </method>
 
-    <method name="PUT" id="updateTenant">
-        <doc xml:lang="EN" title="Update a Tenant">
-            <p xmlns="http://www.w3.org/1999/xhtml">Updates a tenant.</p>
+    <method name="POST" id="updateTenant">
+        <doc xml:lang="EN" title="Update Tenant">
+            <p xmlns="http://www.w3.org/1999/xhtml" class="shortdesc">
+                Updates a tenant.
+            </p>
+            <p xmlns="http://www.w3.org/1999/xhtml">This call updates a tenant.</p>
+            <examples xmlns="http://docs.rackspace.com/api" title="Tenant Update Request">
+                <example href="../common/samples/tenant.xml" language="xml"/>
+                <example href="../common/samples/tenant.json" language="javascript"/>
+            </examples>
+            <examples xmlns="http://docs.rackspace.com/api" title="Tenant Update Response">
+                <example href="../common/samples/tenant.xml" language="xml"/>
+                <example href="../common/samples/tenant.json" language="javascript"/>
+            </examples>            
         </doc>
         <request>
             <representation mediaType="application/xml" element="identity:tenant"/>
@@ -183,7 +190,10 @@
 
     <method name="DELETE" id="deleteTenant">
         <doc xml:lang="EN" title="Delete a Tenant">
-            <p xmlns="http://www.w3.org/1999/xhtml">Deletes a tenant.</p>
+            <p xmlns="http://www.w3.org/1999/xhtml" class="shortdesc">
+                Deletes a tenant.
+            </p>
+            <p xmlns="http://www.w3.org/1999/xhtml">This call deletes a tenant.</p>
         </doc>
         <response status="204"/>
         &commonFaults;
@@ -192,7 +202,12 @@
     
     <method name="GET" id="listRolesForTenant">
         <doc xml:lang="EN" title="List roles for a Tenant.">
+            <p xmlns="http://www.w3.org/1999/xhtml" class="shortdesc">Lists all the roles for a tenant.</p>
             <p xmlns="http://www.w3.org/1999/xhtml">Lists all the roles for a tenant.</p>
+            <examples xmlns="http://docs.rackspace.com/api" title="List Roles for Tenant Response">
+                <example href="../common/samples/roles.xml" language="xml"/>
+                <example href="../common/samples/roles.json" language="javascript"/>
+            </examples>            
         </doc>
         <request>
             <param name="marker" style="query" required="false" type="xsd:string"/>
@@ -207,8 +222,13 @@
     </method>
 
     <method name="GET" id="listUsersForTenant">
-        <doc xml:lang="EN" title="List users for a Tenants">
+        <doc xml:lang="EN" title="List users for a Tenant.">
+            <p xmlns="http://www.w3.org/1999/xhtml" class="shortdesc">Lists all the users for a tenant.</p>
             <p xmlns="http://www.w3.org/1999/xhtml">Lists all the users for a tenant.</p>
+            <examples xmlns="http://docs.rackspace.com/api" title="List Users for Tenant Response">
+                <example href="../common/samples/users.xml" language="xml"/>
+                <example href="../common/samples/users.json" language="javascript"/>
+            </examples>            
         </doc>
         <request>
             <param name="marker" style="query" required="false" type="xsd:string"/>
@@ -225,6 +245,10 @@
     <method name="GET" id="listUsersWithRoleForTenant">
         <doc xml:lang="EN" title="List user with role for tenant.">
             <p xmlns="http://www.w3.org/1999/xhtml">Lists all the users with a specific role for a tenant.</p>
+            <examples xmlns="http://docs.rackspace.com/api" title="List Users with a specific role for a Tenant Response">
+                <example href="../common/samples/users.xml" language="xml"/>
+                <example href="../common/samples/users.json" language="javascript"/>
+            </examples>            
         </doc>
         <request>
             <param name="roleId" style="query" required="true" type="xsd:string"/>
@@ -262,6 +286,14 @@
     <method name="POST" id="addUser">
         <doc xml:lang="EN" title="Add user">
             <p xmlns="http://www.w3.org/1999/xhtml">Adds a user.</p>
+            <examples xmlns="http://docs.rackspace.com/api" title="User Creation Request">
+                <example href="../common/samples/userwithoutid.xml" language="xml"/>
+                <example href="../common/samples/userwithoutid.json" language="javascript"/>
+            </examples>
+            <examples xmlns="http://docs.rackspace.com/api" title="User Creation Response">
+                <example href="../common/samples/user.xml" language="xml"/>
+                <example href="../common/samples/user.json" language="javascript"/>
+            </examples>            
         </doc>
         <request>
             <representation mediaType="application/xml" element="identity:user"/>
@@ -276,21 +308,17 @@
         &postPutFaults;
     </method>
    
-    <method name="GET" id="getUser">
-        <doc xml:lang="EN" title="Get user">
-            <p xmlns="http://www.w3.org/1999/xhtml">Get user.</p>
-        </doc>
-        <response status="200 203">
-            <representation mediaType="application/xml" element="identity:user"/>
-            <representation mediaType="application/json"/>
-        </response>
-        &commonFaults;
-        &getFaults;
-    </method>
-
-    <method name="PUT" id="updateUser">
+    <method name="POST" id="updateUser">
         <doc xml:lang="EN" title="Update user">
             <p xmlns="http://www.w3.org/1999/xhtml">Update a user.</p>
+            <examples xmlns="http://docs.rackspace.com/api" title="User Updation Request">
+                <example href="../common/samples/user.xml" language="xml"/>
+                <example href="../common/samples/user.json" language="javascript"/>
+            </examples>
+            <examples xmlns="http://docs.rackspace.com/api" title="User Updation Response">
+                <example href="../common/samples/user.xml" language="xml"/>
+                <example href="../common/samples/user.json" language="javascript"/>
+            </examples>               
         </doc>
         <request>
             <representation mediaType="application/xml" element="identity:user"/>
@@ -317,6 +345,14 @@
     <method name="PUT" id="setUserEnabled">
         <doc xml:lang="EN" title="Set user enabled.">
             <p xmlns="http://www.w3.org/1999/xhtml">Enable user.</p>
+            <examples xmlns="http://docs.rackspace.com/api" title="Set user enabled Request">
+                <example href="../common/samples/userwithenabledonly.xml" language="xml"/>
+                <example href="../common/samples/userwithenabledonly.json" language="javascript"/>
+            </examples>
+            <examples xmlns="http://docs.rackspace.com/api" title="Set user enabled Response">
+                <example href="../common/samples/user.xml" language="xml"/>
+                <example href="../common/samples/user.json" language="javascript"/>
+            </examples>             
         </doc>
         <request>
             <representation mediaType="application/xml" element="identity:user">
@@ -337,6 +373,10 @@
     <method name="GET" id="listUserRoles">
         <doc xml:lang="EN" title="List Roles">
             <p xmlns="http://www.w3.org/1999/xhtml">List roles for a user.</p>
+            <examples xmlns="http://docs.rackspace.com/api" title="List Roles for User Response">
+                <example href="../common/samples/roles.xml" language="xml"/>
+                <example href="../common/samples/roles.json" language="javascript"/>
+            </examples>            
         </doc>
         <request>
             <param name="serviceId" style="query" required="false" type="xsd:string"/>
@@ -361,7 +401,11 @@
     
     <method name="GET" id="getUserRole">
         <doc xml:lang="EN" title="Get user Role">
-            <p xmlns="http://www.w3.org/1999/xhtml">Get a role.</p>
+            <p xmlns="http://www.w3.org/1999/xhtml">Get information about a role that belongs to a user.</p>
+            <examples xmlns="http://docs.rackspace.com/api" title="List Roles for User Response">
+                <example href="../common/samples/role.xml" language="xml"/>
+                <example href="../common/samples/role.json" language="javascript"/>
+            </examples>            
         </doc>
         <response status="200 203">
             <representation mediaType="application/xml" element="identity:role"/>
@@ -441,6 +485,19 @@
         &getFaults;
     </method>
     
+    <method name="POST" id="deleteUserCredential">
+        <doc xml:lang="EN" title="Update user credential">
+            <p xmlns="http://www.w3.org/1999/xhtml">Delete credentials.</p>
+        </doc>
+        <response status="200">
+            <representation mediaType="application/xml" element="identity:credentials"/>
+            <representation mediaType="application/json"/>
+        </response>
+        &commonFaults;
+        &postPutFaults;
+        &getFaults;
+    </method>
+    
     <method name="GET" id="getUserCredential">
         <doc xml:lang="EN" title="Get user Credentials">
             <p xmlns="http://www.w3.org/1999/xhtml">Get user credentials.</p>
@@ -457,9 +514,15 @@
     <method name="GET" id="listRoles">
         <doc xml:lang="EN" title="List Roles">
             <p xmlns="http://www.w3.org/1999/xhtml">List roles.</p>
+            <examples xmlns="http://docs.rackspace.com/api" title="List Roles Response">
+                <example href="../common/samples/roles.xml" language="xml"/>
+                <example href="../common/samples/roles.json" language="javascript"/>
+            </examples>            
         </doc>
         <request>
             <param name="serviceId" style="query" required="false" type="xsd:string"/>
+            <param name="marker" style="query" required="false" type="xsd:string"/>
+            <param name="limit" style="query" required="false" type="xsd:int"/>
         </request>
         <response status="200 203">
             <representation mediaType="application/xml" element="identity:roles"/>
@@ -471,9 +534,30 @@
 
     <method name="PUT" id="addRole">
         <doc xml:lang="EN" title="Add Role">
-            <p xmlns="http://www.w3.org/1999/xhtml">Add role.</p>
-        </doc>
-        <response status="200"/>
+            <p xmlns="http://www.w3.org/1999/xhtml">Add a Role.</p>
+            
+            <examples xmlns="http://docs.rackspace.com/api" title="Add a Role Request">
+                <example href="../common/samples/role.xml" language="xml"/>
+                <example href="../common/samples/role.json" language="javascript"/>
+            </examples>            
+            
+            <examples xmlns="http://docs.rackspace.com/api" title="Add a Role Response">
+                <example href="../common/samples/role.xml" language="xml"/>
+                <example href="../common/samples/role.json" language="javascript"/>
+            </examples>
+        </doc>        
+        <request>
+            <representation mediaType="application/xml" element="identity:role"/>
+            <representation mediaType="application/json"/>
+        </request>
+        <response status="201">
+            <representation mediaType="application/xml" element="identity:role">
+                <param name="Location" type="xsd:anyURI" style="header"/>
+            </representation>
+            <representation mediaType="application/json">
+                <param name="Location" type="xsd:anyURI" style="header"/>
+            </representation>
+        </response>
         &commonFaults;
         &postPutFaults;
         &getFaults;
@@ -482,6 +566,10 @@
     <method name="GET" id="getRole">
         <doc xml:lang="EN" title="Get Role">
             <p xmlns="http://www.w3.org/1999/xhtml">Get a role.</p>
+            <examples xmlns="http://docs.rackspace.com/api" title="Get a role">
+                <example href="../common/samples/role.xml" language="xml"/>
+                <example href="../common/samples/role.json" language="javascript"/>
+            </examples>            
         </doc>
         <response status="200 203">
             <representation mediaType="application/xml" element="identity:role"/>
@@ -503,8 +591,17 @@
 
     <!-- Service Operations -->
     <method name="GET" id="listServices">
+        <doc xml:lang="EN" title="List Services">
+            <p xmlns="http://www.w3.org/1999/xhtml">List services.</p>
+            <examples xmlns="http://docs.rackspace.com/api" title="List services Response">
+                <example href="../common/samples/services.xml" language="xml"/>
+                <example href="../common/samples/services.json" language="javascript"/>
+            </examples>            
+        </doc>
         <request>
             <param name="serviceId" style="query" required="false" type="xsd:string"/>
+            <param name="marker" style="query" required="false" type="xsd:string"/>
+            <param name="limit" style="query" required="false" type="xsd:int"/>
         </request>
         <response status="200 203">
             <representation mediaType="application/xml" element="OS-KSADM:services"/>
@@ -514,6 +611,13 @@
         &getFaults;
     </method>
     <method name="GET" id="getService">
+        <doc xml:lang="EN" title="Get Service">
+            <p xmlns="http://www.w3.org/1999/xhtml">Get a service.</p>
+            <examples xmlns="http://docs.rackspace.com/api" title="Get a service Response">
+                <example href="../common/samples/service.xml" language="xml"/>
+                <example href="../common/samples/service.json" language="javascript"/>
+            </examples>            
+        </doc>
         <response status="200 203">
             <representation mediaType="application/xml" element="OS-KSADM:service"/>
             <representation mediaType="application/json"/>
@@ -521,7 +625,20 @@
         &commonFaults;
         &getFaults;
     </method>
-    <method name="POST" id="addService">
+    <method name="PUT" id="addService">
+        <doc xml:lang="EN" title="Add Service">
+            <p xmlns="http://www.w3.org/1999/xhtml">Add a service.</p>
+            
+            <examples xmlns="http://docs.rackspace.com/api" title="Add a service Request">
+                <example href="../common/samples/service.xml" language="xml"/>
+                <example href="../common/samples/service.json" language="javascript"/>
+            </examples>            
+            
+            <examples xmlns="http://docs.rackspace.com/api" title="Add a service Response">
+                <example href="../common/samples/service.xml" language="xml"/>
+                <example href="../common/samples/service.json" language="javascript"/>
+            </examples>
+        </doc>        
         <request>
             <representation mediaType="application/xml" element="OS-KSADM:service"/>
             <representation mediaType="application/json"/>
@@ -539,6 +656,9 @@
         &getFaults;
     </method>
     <method name="DELETE" id="deleteService">
+        <doc xml:lang="EN" title="Add Service">
+            <p xmlns="http://www.w3.org/1999/xhtml">Delete a service.</p>
+        </doc>    
         <response status="204"/>
         &commonFaults;
         &getFaults;
diff --git a/keystone/content/admin/identity-OS-KSADM-dev-guide.pdf b/keystone/content/admin/identity-OS-KSADM-dev-guide.pdf
new file mode 100644
index 00000000..e5ec2014
--- /dev/null
+++ b/keystone/content/admin/identity-OS-KSADM-dev-guide.pdf
diff --git a/keystone/content/admin/identity-admin.wadl b/keystone/content/admin/identity-admin.wadl
index 6f1e2c53..2af24d56 100644
--- a/keystone/content/admin/identity-admin.wadl
+++ b/keystone/content/admin/identity-admin.wadl
@@ -25,6 +25,7 @@
         <include href="../common/xsd/api.xsd"/>
         <include href="../common/xsd/api-common.xsd"/>
     </grammars>
+
     <!--*******************************************************-->
     <!--             All Resoruces                             -->
     <!--*******************************************************-->
@@ -103,6 +104,23 @@
     </resources>
 
     <!--*******************************************************-->
+    <!--               Resource Types                          -->
+    <!--*******************************************************-->
+    
+    <resource_type id="VersionDetails">
+        <method href="#getVersionInfo"/>
+    </resource_type>
+    
+    <resource_type id="ExtensionList">
+        <doc xml:lang="EN" title="Extension List">
+            <p xmlns="http://www.w3.org/1999/xhtml">
+                A list of supported extensions.
+            </p>
+        </doc>
+        <method href="#listExtensions"/>
+    </resource_type>
+    
+    <!--*******************************************************-->
     <!--               All Methods                             -->
     <!--*******************************************************-->
 
@@ -148,7 +166,7 @@
         &commonFaults;
     </method>
     <method name="GET" id="getExtension">
-        <doc xml:lang="EN" title="Get Server Details">
+        <doc xml:lang="EN" title="Get Extension Details">
             <p xmlns="http://www.w3.org/1999/xhtml">
             	Gets details about a specific extension.
             </p>
diff --git a/keystone/content/common/samples/tenantwithoutid.json b/keystone/content/common/samples/tenantwithoutid.json
new file mode 100644
index 00000000..63faba9c
--- /dev/null
+++ b/keystone/content/common/samples/tenantwithoutid.json
@@ -0,0 +1,7 @@
+{
+  "tenant": {
+    "name": "ACME corp",
+    "description": "A description ...",
+    "enabled": true
+  }
+}
diff --git a/keystone/content/common/samples/tenantwithoutid.xml b/keystone/content/common/samples/tenantwithoutid.xml
new file mode 100644
index 00000000..3983684b
--- /dev/null
+++ b/keystone/content/common/samples/tenantwithoutid.xml
@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<tenant xmlns="http://docs.openstack.org/identity/api/v2.0"
+        enabled="true" name="ACME Corp">
+    <description>A description...</description>
+</tenant>
diff --git a/keystone/content/common/samples/users.json b/keystone/content/common/samples/users.json
new file mode 100644
index 00000000..134d1972
--- /dev/null
+++ b/keystone/content/common/samples/users.json
@@ -0,0 +1,18 @@
+{
+  "users": {
+    "values": [
+      {
+        "id": "u1000",
+        "username": "jqsmith",
+        "email": "john.smith@example.org",
+        "enabled": true
+      }, {
+        "id": "u1001",
+        "username": "jqsmith",
+        "email": "john.smith@example.org",
+        "enabled": true
+      }
+    ],
+    "links":[]
+  }
+}
\ No newline at end of file
diff --git a/keystone/content/common/samples/users.xml b/keystone/content/common/samples/users.xml
new file mode 100644
index 00000000..28e5aa38
--- /dev/null
+++ b/keystone/content/common/samples/users.xml
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<users xmlns="http://docs.openstack.org/identity/api/v2.0">
+    <user xmlns="http://docs.openstack.org/identity/api/v2.0"
+          enabled="true" email="john.smith@example.org"
+          username="jqsmith" id="u1000"/>
+    <user xmlns="http://docs.openstack.org/identity/api/v2.0"
+          enabled="true" email="john.smith@example.org"
+          username="jqsmith" id="u1000"/>
+</users>
diff --git a/keystone/content/common/samples/userwithenabledonly.json b/keystone/content/common/samples/userwithenabledonly.json
new file mode 100644
index 00000000..23265395
--- /dev/null
+++ b/keystone/content/common/samples/userwithenabledonly.json
@@ -0,0 +1,5 @@
+{
+  "user": {
+    "enabled": true
+	}
+}
diff --git a/keystone/content/common/samples/userwithenabledonly.xml b/keystone/content/common/samples/userwithenabledonly.xml
new file mode 100644
index 00000000..3a0af74b
--- /dev/null
+++ b/keystone/content/common/samples/userwithenabledonly.xml
@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<user xmlns="http://docs.openstack.org/identity/api/v2.0"
+      enabled="true"/>
diff --git a/keystone/content/common/samples/userwithoutid.json b/keystone/content/common/samples/userwithoutid.json
new file mode 100644
index 00000000..2a891811
--- /dev/null
+++ b/keystone/content/common/samples/userwithoutid.json
@@ -0,0 +1,7 @@
+{
+  "user": {
+    "username": "jqsmith",
+    "email": "john.smith@example.org",
+    "enabled": true
+	}
+}
diff --git a/keystone/content/common/samples/userwithoutid.xml b/keystone/content/common/samples/userwithoutid.xml
new file mode 100644
index 00000000..3e875beb
--- /dev/null
+++ b/keystone/content/common/samples/userwithoutid.xml
@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<user xmlns="http://docs.openstack.org/identity/api/v2.0"
+      enabled="true" email="john.smith@example.org"
+      username="jqsmith"/>
diff --git a/keystone/content/common/xsd/user.xsd b/keystone/content/common/xsd/user.xsd
index b0a1123e..cae6a546 100644
--- a/keystone/content/common/xsd/user.xsd
+++ b/keystone/content/common/xsd/user.xsd
@@ -45,7 +45,7 @@
 
     <!-- Complex Types -->
     <complexType name="User">
-        <attribute name="id" type="xsd:ID" use="required">            
+        <attribute name="id" type="xsd:ID" use="optional">            
             <annotation>
                 <xsd:documentation
                     xml:lang="EN"