From 1e0d453b1fec070233181bd18c76f36db85fb3b0 Mon Sep 17 00:00:00 2001
From: Atsushi SAKAI <sakaia@jp.fujitsu.com>
Date: Thu, 13 Aug 2015 11:30:50 +0900
Subject: [PATCH] Add description of discoverability API (GET /info)

I am wondering which keyword is better
middleware or capability.

Change-Id: Idce809a943a2dc4acd7a259ffb2c3aab08288103
Closes-Bug: #1329041
---
 api-ref/src/docbkx/ch_objectstorage-v1.xml    | 13 ++++++++
 api-ref/src/wadls/object-api/src/common.ent   | 23 +++++++++++++
 .../object-api/src/os-object-api-1.0.wadl     | 33 ++++++++++++++++++-
 .../object-api/src/samples/info_response.json |  7 ++++
 4 files changed, 75 insertions(+), 1 deletion(-)
 create mode 100644 api-ref/src/wadls/object-api/src/samples/info_response.json

diff --git a/api-ref/src/docbkx/ch_objectstorage-v1.xml b/api-ref/src/docbkx/ch_objectstorage-v1.xml
index 6bce11dd5..e5a09635e 100644
--- a/api-ref/src/docbkx/ch_objectstorage-v1.xml
+++ b/api-ref/src/docbkx/ch_objectstorage-v1.xml
@@ -45,6 +45,19 @@ Accept-Ranges: bytes</programlisting>
         see <link
             xlink:href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14"
             >Header Field Definitions</link>.</para>
+    <section xml:id="storage_info">
+        <title>Discoverability</title>
+        <para>
+            If configured, lists the activated capabilities for this version
+            of the OpenStack Object Storage API.
+        </para>
+        <wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
+            <wadl:resource
+                href="../wadls/object-api/src/os-object-api-1.0.wadl#info">
+                <wadl:method href="#infoDiscoverability"/>
+            </wadl:resource>
+        </wadl:resources>
+    </section>
     <section xml:id="storage_endpoints">
         <title>Endpoints</title>
         <para>If configured, lists endpoints for a specified account.</para>
diff --git a/api-ref/src/wadls/object-api/src/common.ent b/api-ref/src/wadls/object-api/src/common.ent
index 49d2faebf..b891b764c 100644
--- a/api-ref/src/wadls/object-api/src/common.ent
+++ b/api-ref/src/wadls/object-api/src/common.ent
@@ -604,6 +604,29 @@ include them in this header.</para>
 </param>
 '>
 <!--! Request parameters  -->
+<!ENTITY info-requestParameter '
+    <param xmlns="http://wadl.dev.java.net/2009/02" name="swiftinfo_sig"
+    style="query" required="false" type="xsd:char">
+    <wadl:doc xmlns="http://docbook.org/ns/docbook"
+        xmlns:wadl="http://wadl.dev.java.net/2009/02" xml:lang="EN"
+            >
+        <para>
+            A hash-based message authentication code (HMAC) that enables
+            access to administrator-only information. To use this parameter,
+            the <code>swiftinfo_expires</code> parameter is also required.
+        </para>
+    </wadl:doc>
+</param>
+    <param xmlns="http://wadl.dev.java.net/2009/02" name="swiftinfo_expires"
+    style="query" required="false" type="xsd:int">
+    <wadl:doc xmlns="http://docbook.org/ns/docbook"
+        xmlns:wadl="http://wadl.dev.java.net/2009/02" xml:lang="EN"
+            >
+        <para>
+            Sets the expiration time in UNIX Epoch timestamp format.
+        </para>
+        </wadl:doc>
+</param>'>
 <!ENTITY delimiter-requestParameter '<param xmlns="http://wadl.dev.java.net/2009/02" name="delimiter"
     style="query" required="false" type="xsd:char">
     <wadl:doc xmlns="http://docbook.org/ns/docbook"
diff --git a/api-ref/src/wadls/object-api/src/os-object-api-1.0.wadl b/api-ref/src/wadls/object-api/src/os-object-api-1.0.wadl
index 99eb622ec..7fdefc605 100644
--- a/api-ref/src/wadls/object-api/src/os-object-api-1.0.wadl
+++ b/api-ref/src/wadls/object-api/src/os-object-api-1.0.wadl
@@ -76,6 +76,9 @@
                 </resource>
             </resource>
         </resource>
+        <resource id="info" path="//info">
+            <method href="#infoDiscoverability"/>
+        </resource>
     </resources>
     <!--*******************************************************-->
     <!--               Resource Types                          -->
@@ -93,6 +96,35 @@
     <!--               All Methods                             -->
     <!--*******************************************************-->
 
+    <method name="GET" id="infoDiscoverability">
+        <wadl:doc xmlns="http://docbook.org/ns/docbook"
+            xmlns:wadl="http://wadl.dev.java.net/2009/02" xml:lang="EN"
+            title="List activated capabilities">
+            <para role="shortdesc">
+                Lists the activated capabilities for this version of the
+                OpenStack Object Storage API.
+            </para>
+        </wadl:doc>
+        <request>
+            <representation mediaType="application/xml">
+                &info-requestParameter;
+            </representation>
+        </request>
+        <!--No request body is provided-->
+        <response status="200">
+            <representation mediaType="application/json">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
+                    <xsdxt:sample>
+                        <xsdxt:code
+                            href="samples/info_response.json"
+                        />
+                    </xsdxt:sample>
+                </wadl:doc>
+            </representation>
+        </response>
+    </method>
+    <!--*******************************************************-->
     <method name="GET" id="listEndpoints">
         <wadl:doc xmlns="http://docbook.org/ns/docbook"
             xmlns:wadl="http://wadl.dev.java.net/2009/02" xml:lang="EN"
@@ -127,7 +159,6 @@
             </representation>
         </response>
     </method>
-
     <!--*******************************************************-->
     <!--               Account-level operations                -->
     <!--*******************************************************-->
diff --git a/api-ref/src/wadls/object-api/src/samples/info_response.json b/api-ref/src/wadls/object-api/src/samples/info_response.json
new file mode 100644
index 000000000..bcc91f7d5
--- /dev/null
+++ b/api-ref/src/wadls/object-api/src/samples/info_response.json
@@ -0,0 +1,7 @@
+{
+    "swift": {
+        "version": "1.11.0"
+    },
+    "staticweb": {},
+    "tempurl": {}
+}