From 6dd32c6c92e3734c44fa39533eadabb148319062 Mon Sep 17 00:00:00 2001
From: Atsushi SAKAI <sakaia@jp.fujitsu.com>
Date: Fri, 18 Sep 2015 09:59:57 +0900
Subject: [PATCH] Compute v2.1 docs clean up (part15) (os-block-device-mapping)

  WADL file and JSON files are from v2 ext.
    Removes listServers
       (since it does not exist on
       nova/nova/api/openstack/compute/block_device_mapping.py)
    Adds block-device-mapping-v1
    URL path is changed from /v2 to /v2.1
    Keep JSON sample files only (XML sample files are not included)

P.S.
  All attributes of block-device mapping is in
    https://github.com/openstack/nova/blob/stable/kilo/nova/block_device.py
  (Both version)

Change-Id: I5aa201102aabd4b7581002f6eccca0b67e070fcb
Partial-Bug: #1488144
---
 api-ref/src/docbkx/ch_compute-v2.1.xml        |   8 ++
 .../server-post-req.json                      |  33 ++++++
 .../server-post-resp.json                     |  16 +++
 .../src/wadls/compute-api/src/v2.1/common.ent | 109 +++++++++++++++---
 .../wadl/os-block-device-mapping-v2.1.wadl    | 104 +++++++++++++++++
 5 files changed, 257 insertions(+), 13 deletions(-)
 create mode 100644 api-ref/src/wadls/compute-api/src/v2.1/api_samples/os-block-device-mapping/server-post-req.json
 create mode 100644 api-ref/src/wadls/compute-api/src/v2.1/api_samples/os-block-device-mapping/server-post-resp.json
 create mode 100644 api-ref/src/wadls/compute-api/src/v2.1/wadl/os-block-device-mapping-v2.1.wadl

diff --git a/api-ref/src/docbkx/ch_compute-v2.1.xml b/api-ref/src/docbkx/ch_compute-v2.1.xml
index 3db3d5292..57a4aee9a 100644
--- a/api-ref/src/docbkx/ch_compute-v2.1.xml
+++ b/api-ref/src/docbkx/ch_compute-v2.1.xml
@@ -412,6 +412,14 @@
          href="../wadls/compute-api/src/v2.1/wadl/os-baremetal-nodes-v2.1.wadl"
          xmlns:wadl="http://wadl.dev.java.net/2009/02"/>
    </section>
+   <section xml:id="os-block-device-mapping-v2.1">
+      <title>Servers with block device mapping format
+          (servers, os-block-device-mapping)</title>
+      <para>Creates a server with a block device mapping.</para>
+      <wadl:resources
+          href="../wadls/compute-api/src/v2.1/wadl/os-block-device-mapping-v2.1.wadl"
+          xmlns:wadl="http://wadl.dev.java.net/2009/02"/>
+   </section>
    <section xml:id="os-cells-v2.1">
       <title>Cells (os-cells, capacities)</title>
       <para>
diff --git a/api-ref/src/wadls/compute-api/src/v2.1/api_samples/os-block-device-mapping/server-post-req.json b/api-ref/src/wadls/compute-api/src/v2.1/api_samples/os-block-device-mapping/server-post-req.json
new file mode 100644
index 000000000..41983de60
--- /dev/null
+++ b/api-ref/src/wadls/compute-api/src/v2.1/api_samples/os-block-device-mapping/server-post-req.json
@@ -0,0 +1,33 @@
+{
+    "server": {
+        "name": "new-server-test",
+        "imageRef": "http://openstack.example.com/openstack/images/70a599e0-31e7-49b7-b260-868f441e862b",
+        "flavorRef": "http://openstack.example.com/openstack/flavors/1",
+        "metadata": {
+            "My Server Name": "Apache1"
+        },
+        "personality": [
+            {
+                "path": "/etc/banner.txt",
+                "contents": "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBpdCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5kIGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVsc2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4gQnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRoZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlvdSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vyc2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6b25zLiINCg0KLVJpY2hhcmQgQmFjaA=="
+            }
+        ],
+        "block_device_mapping_v2": [
+            {
+                "device_name": "/dev/sdb1",
+                "source_type": "blank",
+                "destination_type": "local",
+                "delete_on_termination": "True",
+                "guest_format": "swap",
+                "boot_index": "-1"
+            },
+            {
+                "device_name": "/dev/sda1",
+                "source_type": "volume",
+                "destination_type": "volume",
+                "uuid": "fake-volume-id-1",
+                "boot_index": "0"
+            }
+        ]
+    }
+}
diff --git a/api-ref/src/wadls/compute-api/src/v2.1/api_samples/os-block-device-mapping/server-post-resp.json b/api-ref/src/wadls/compute-api/src/v2.1/api_samples/os-block-device-mapping/server-post-resp.json
new file mode 100644
index 000000000..d3a4f558c
--- /dev/null
+++ b/api-ref/src/wadls/compute-api/src/v2.1/api_samples/os-block-device-mapping/server-post-resp.json
@@ -0,0 +1,16 @@
+{
+    "server": {
+        "adminPass": "N4x7wFX6iN8D",
+        "id": "babd1af0-4fc6-4529-b32f-aad69811ccf5",
+        "links": [
+            {
+                "href": "http://openstack.example.com/v2/openstack/servers/babd1af0-4fc6-4529-b32f-aad69811ccf5",
+                "rel": "self"
+            },
+            {
+                "href": "http://openstack.example.com/openstack/servers/babd1af0-4fc6-4529-b32f-aad69811ccf5",
+                "rel": "bookmark"
+            }
+        ]
+    }
+}
diff --git a/api-ref/src/wadls/compute-api/src/v2.1/common.ent b/api-ref/src/wadls/compute-api/src/v2.1/common.ent
index dbcf57314..9585a06b8 100644
--- a/api-ref/src/wadls/compute-api/src/v2.1/common.ent
+++ b/api-ref/src/wadls/compute-api/src/v2.1/common.ent
@@ -135,7 +135,7 @@
 <option value="SERVER"/>
 <option value="ALL"/>
    </param>'>
-<!-- Server Create Parameters -->
+<!-- Server Create Request Parameters -->
 <!ENTITY serverCreateParameters '
 <param xmlns="http://wadl.dev.java.net/2009/02"
    name="security_group" style="query" required="true"
@@ -178,22 +178,71 @@
 <wadl:doc xmlns="http://docbook.org/ns/docbook"
    xmlns:wadl="http://wadl.dev.java.net/2009/02"
    xml:lang="EN" title="server">
-   <para>server.</para>
+   <para>A <code>server</code> object.</para>
 </wadl:doc>
 </param>
-<param name="imageRef" style="plain" required="true"
+<param name="imageRef" style="plain" required="false"
    xmlns:csapi="http://docs.openstack.org/compute/api/v2"
    xmlns="http://wadl.dev.java.net/2009/02"
    type="csapi:string">
-<wadl:doc xmlns="http://docbook.org/ns/docbook"
-   xmlns:wadl="http://wadl.dev.java.net/2009/02"
-   xml:lang="EN" title="imageRef">
-   <para>The image reference for the desired image
-      for your server instance.
-   </para>
-   <para>Specify as an ID or full URL.
-   </para>
-</wadl:doc>
+   <wadl:doc xmlns="http://docbook.org/ns/docbook"
+      xmlns:wadl="http://wadl.dev.java.net/2009/02"
+      xml:lang="EN" title="imageRef">
+      <para>
+        Required if you define a block device mapping.
+      </para>
+      <para>
+        The image reference as an ID or full URL for the image for your server
+        instance.
+      </para>
+   </wadl:doc>
+</param>
+<param name="block_device_mapping_v2" style="plain" required="false"
+   xmlns:csapi="http://docs.openstack.org/compute/api/v2"
+   xmlns="http://wadl.dev.java.net/2009/02"
+   type="csapi:string">
+   <wadl:doc xmlns="http://docbook.org/ns/docbook"
+      xmlns:wadl="http://wadl.dev.java.net/2009/02"
+      xml:lang="EN" title="block_device_mapping_v2">
+      <para>
+        The block device mapping information. Mutually exclusive with
+        <code>block_device_mapping</code>.
+      </para>
+   </wadl:doc>
+</param>
+<param name="block_device_mapping" style="plain" required="false"
+   xmlns:csapi="http://docs.openstack.org/compute/api/v2"
+   xmlns="http://wadl.dev.java.net/2009/02"
+   type="csapi:string">
+   <wadl:doc xmlns="http://docbook.org/ns/docbook"
+      xmlns:wadl="http://wadl.dev.java.net/2009/02"
+      xml:lang="EN" title="block_device_mapping">
+      <para>
+        The block device mapping information. Mutually exclusive with
+        <code>block_device_mapping_v2</code>.
+      </para>
+   </wadl:doc>
+</param>
+<param name="delete_on_termination" style="plain" required="false"
+   xmlns:csapi="http://docs.openstack.org/compute/api/v2"
+   xmlns="http://wadl.dev.java.net/2009/02"
+   type="xsd:boolean">
+   <wadl:doc xmlns="http://docbook.org/ns/docbook"
+      xmlns:wadl="http://wadl.dev.java.net/2009/02"
+      xml:lang="EN" title="delete_on_termination">
+      <para>
+        Defines whether to delete or keep the attached volume when the server
+        is deleted.
+      </para>
+      <para>
+        Set to <code>True</code> to delete the attached volume when the server
+        is deleted. Set to <code>False</code> to keep the attached volume when
+        the server is deleted.
+      </para>
+      <para>
+        Part of a block device mapping definition.
+      </para>
+   </wadl:doc>
 </param>
 <param name="flavorRef" style="plain" required="true"
    xmlns:csapi="http://docs.openstack.org/compute/api/v2"
@@ -248,6 +297,40 @@
    </para>
 </wadl:doc>
 </param>'>
+<!ENTITY serverCreateResponseParameters '
+<param xmlns="http://wadl.dev.java.net/2009/02"
+   name="server" style="plain" required="true"
+   type="csapi:ServerForCreate" path="/csapi:server">
+<wadl:doc xmlns="http://docbook.org/ns/docbook"
+   xmlns:wadl="http://wadl.dev.java.net/2009/02"
+   xml:lang="EN" title="server">
+   <para>A <code>server</code> object.</para>
+</wadl:doc>
+</param>
+<param xmlns="http://wadl.dev.java.net/2009/02"
+   name="adminPass" style="plain" required="true" type="csapi:string">
+<wadl:doc xmlns="http://docbook.org/ns/docbook"
+   xmlns:wadl="http://wadl.dev.java.net/2009/02"
+   xml:lang="EN" title="adminPass">
+   <para>The administrative password for the server.</para>
+</wadl:doc>
+</param>
+<param name="id" style="plain" type="csapi:UUID" required="true"
+  xmlns="http://wadl.dev.java.net/2009/02">
+  <wadl:doc xmlns="http://docbook.org/ns/docbook"
+   xml:lang="EN"
+   xmlns:wadl="http://wadl.dev.java.net/2009/02">
+    <para>The server ID.</para>
+  </wadl:doc>
+</param>
+<param xmlns="http://wadl.dev.java.net/2009/02"
+  name="links" style="plain" required="true" type="xsd:string">
+<wadl:doc xmlns="http://docbook.org/ns/docbook"
+  xmlns:wadl="http://wadl.dev.java.net/2009/02"
+  xml:lang="EN">
+  <para>Server links.</para>
+</wadl:doc>
+</param>'>
 <!-- tenantIdRequestParameter -->
 <!ENTITY tenantIdRequestParameter '
 <param name="tenant_id" style="template" type="csapi:UUID"
@@ -787,7 +870,7 @@
 </wadl:doc>
 </param>
 <param xmlns="http://wadl.dev.java.net/2009/02"
-  name="links"  style="plain" required="true" type="xsd:string">
+  name="links" style="plain" required="true" type="xsd:string">
 <wadl:doc xmlns="http://docbook.org/ns/docbook"
   xmlns:wadl="http://wadl.dev.java.net/2009/02"
   xml:lang="EN">
diff --git a/api-ref/src/wadls/compute-api/src/v2.1/wadl/os-block-device-mapping-v2.1.wadl b/api-ref/src/wadls/compute-api/src/v2.1/wadl/os-block-device-mapping-v2.1.wadl
new file mode 100644
index 000000000..6f575131a
--- /dev/null
+++ b/api-ref/src/wadls/compute-api/src/v2.1/wadl/os-block-device-mapping-v2.1.wadl
@@ -0,0 +1,104 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- (C) 2013-2015 OpenStack Foundation, All Rights Reserved -->
+<!--*******************************************************-->
+<!--         Import Common XML Entities                    -->
+<!--                                                       -->
+<!--     You can resolve the entities with xmllint          -->
+<!--                                                       -->
+<!--        xmllint -noent os-block-device-mapping-v2.1.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:xsd="http://www.w3.org/2001/XMLSchema"
+    xmlns:wadl="http://wadl.dev.java.net/2009/02"
+    xmlns:db="http://docbook.org/ns/docbook"
+    xmlns:common="http://docs.openstack.org/common/api/v1.0"
+    xmlns:csapi="http://docs.openstack.org/compute/api/v2">
+    <grammars>
+        <include href="../xsd/api.xsd"/>
+        <include href="../xsd/api-common.xsd"/>
+    </grammars>
+    <!--*******************************************************-->
+    <!--             All Resources                             -->
+    <!--*******************************************************-->
+    <resources base="https://servers.api.openstack.com"
+        xml:id="block_device_mapping_v2.1">
+        <resource id="version" type="#VersionDetails" path="//v2.1">
+            <resource id="tenantID" path="{tenant_id}">
+                <param name="tenant_id" style="template"
+                    type="xsd:string">
+                    <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                        xml:lang="EN">
+                        <para>The tenant ID in a multi-tenancy
+                            cloud.</para>
+                    </wadl:doc>
+                </param>
+                <resource id="Servers" type="#ServerList"
+                    path="servers">
+                    <method href="#createServer"/>
+                </resource>
+            </resource>
+        </resource>
+    </resources>
+    <!--*******************************************************-->
+    <!--               All Methods                             -->
+    <!--*******************************************************-->
+
+    <!-- Servers -->
+    <method name="POST" id="createServer">
+        <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
+            title="Create server with block device mapping">
+            <para role="shortdesc">
+                Creates a server with a block device mapping.
+            </para>
+            <para>
+                To define the block device mapping, you can include either a
+                <code>block_device_mapping</code> or
+                <code>block_device_mapping_v2</code> object in the request
+                body. The <code>block_device_mapping_v2</code> object is
+                preferred.
+            </para>
+        </wadl:doc>
+        <request>
+            <representation mediaType="application/json">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
+                    <xsdxt:code
+                        href="../api_samples/os-block-device-mapping/server-post-req.json"
+                    />
+                </wadl:doc>
+            </representation>
+            <representation mediaType="application/xml"
+                element="csapi:server">
+                &serverCreateParameters;
+            </representation>
+        </request>
+        <response status="202">
+            <representation mediaType="application/json">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
+                    <xsdxt:code
+                        href="../api_samples/os-block-device-mapping/server-post-resp.json"
+                    />
+                </wadl:doc>
+            </representation>
+            <representation mediaType="application/xml"
+                element="csapi:server">
+                &serverCreateResponseParameters;
+            </representation>
+        </response>
+        <response status="422">
+            <representation mediaType="application/json"/>
+            <representation mediaType="application/xml"
+                element="csapi:UnprocessableEntity"/>
+        </response>
+        &commonFaults; &getFaults;
+        &postPutFaults; &buildFaults;
+    </method>
+</application>