openstack-attic/compute-api
Code Issues Proposed changes

Merge "Fix error in request/response formats section"

Browse Source
This commit is contained in:
Jenkins
2014-06-22 14:45:55 +00:00
committed by Gerrit Code Review
parent 38a1681acd 0455e0f2f8
commit 657292543f
2 changed files with 117 additions and 87 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
pom.xml
View File

@@ -39,7 +39,7 @@
<plugin> <plugin>
<groupId>com.rackspace.cloud.api</groupId> <groupId>com.rackspace.cloud.api</groupId>
<artifactId>clouddocs-maven-plugin</artifactId> <artifactId>clouddocs-maven-plugin</artifactId>
<version>2.0.2</version> <version>2.0.4</version>
</plugin> </plugin>
</plugins> </plugins>
</build> </build>

154
v2/bk_compute_api_ref_v2.xml
View File

@@ -547,55 +547,76 @@
</note> </note>
</section> </section>
<section xml:id="Request_Response_Types-d1e459"> <section xml:id="Request_Response_Types-d1e459">
<title>Request and response types</title> <title>Request and response formats</title>
<para>The OpenStack Compute API supports both JSON and XML <para>The OpenStack Compute API supports both JSON and XML
data serialization request and response data serialization request and response
formats.</para> formats.</para>
<para>You specify the request format in the <section xml:id="request-format">
<code>Content-Type</code> header in the request. <title>Request format</title>
This header is required for operations that have a <para>Use the <code>Content-Type</code> request header
request body. The syntax for the to specify the request format. This header is
<code>Content-Type</code> header is:</para> required for operations that have a request body.</para>
<programlisting>Content-Type: application/<parameter>format</parameter></programlisting> <para>The syntax for the <code>Content-Type</code>
<para>Where <parameter>format</parameter> is either header is:</para>
<literal>json</literal> or <literal>xml</literal>, <programlisting>Content-Type: application/<replaceable>FORMAT</replaceable></programlisting>
you specify the response format by using one of the <para>Where <replaceable>FORMAT</replaceable> is
following methods:</para> either <literal>json</literal> or
<itemizedlist> <literal>xml</literal>.</para>
</section>
<section xml:id="response-format">
<title>Response format</title>
<para>Use one of the following methods to specify the
response format:</para>
<variablelist>
<varlistentry>
<term><code>Accept</code> header</term>
<listitem> <listitem>
<para><code>Accept</code> header. The syntax for <para>The syntax for the
the <code>Accept</code> header is: <code>Accept</code> header
<programlisting>Accept: application/<parameter>format</parameter></programlisting></para> is:</para>
<para>Where <parameter>format</parameter> is <programlisting>Accept: application/<replaceable>FORMAT</replaceable></programlisting>
either <constant>json</constant> or <para>Where
<constant>xml</constant>, the default <replaceable>FORMAT</replaceable>
format is <literal>json</literal>.</para> is either <literal>json</literal> or
<literal>xml</literal>. The default
format is
<literal>json</literal>.</para>
</listitem> </listitem>
</varlistentry>
<varlistentry>
<term>Query extension</term>
<listitem> <listitem>
<para>Query extension. Add an <para>Add an <literal>.xml</literal> or
<literal>.xml</literal> or <literal>.json</literal> extension
<literal>.json</literal> extension to the to the request URI. For example, the
request URI. For example, the <literal>.xml</literal> extension
<literal>.xml</literal> extension in the in the following list servers URI
following URI request specifies that the request specifies that the response
response body is returned in XML format: body is to be returned in XML
<literallayout role="monospace">&POST; /v2/010101/servers.xml</literallayout></para> format:</para>
<literallayout role="monospace">&GET; <replaceable>publicURL</replaceable>/servers.xml</literallayout>
</listitem> </listitem>
</itemizedlist> </varlistentry>
<para>If you do not specify a response format, JSON is the </variablelist>
default.</para> <para>If you do not specify a response format, JSON is
<para>If you specify conflicting formats in the the default.</para>
<code>Accept</code> header and the query <para>If the <code>Accept</code> header and the query
extension, the format specified in the query extension extension specify conflicting formats, the format
takes precedence. For example, if the query extension specified in the query extension takes precedence.
is <literal>.xml</literal> and the <code>Accept</code> For example, if the query extension is
header specifies <literal>application/json</literal>, <literal>.xml</literal> and the
the response is returned in XML format.</para> <code>Accept</code> header specifies
<para>You can serialize a response in a different format <literal>application/json</literal>, the
from the request format. <xref linkend="JSON_req"/> response is returned in XML format.</para>
and <xref linkend="ImageCreateFullResponse"/> show a </section>
request body in JSON format and a response body in XML <section xml:id="request-response-examples">
format.</para> <title>Request and response examples</title>
<para>You can serialize a response in a different
format from the request format.</para>
<para><xref linkend="JSON_req"/> and <xref
linkend="ImageCreateFullResponse"/> show a
request body in JSON format and a response body in
XML format.</para>
<example xml:id="JSON_req"> <example xml:id="JSON_req">
<title>JSON request with headers</title> <title>JSON request with headers</title>
<literallayout role="monospace"><?db-font-size 70%?>POST /v2/010101/servers HTTP/1.1 <literallayout role="monospace"><?db-font-size 70%?>POST /v2/010101/servers HTTP/1.1
@@ -606,8 +627,8 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb</literallayout>
<programlisting language="json"><?db-font-size 70%?><xi:include href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/compute-api/src/v2/api_samples/server-post-req.json" parse="text"/></programlisting> <programlisting language="json"><?db-font-size 70%?><xi:include href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/compute-api/src/v2/api_samples/server-post-req.json" parse="text"/></programlisting>
</example> </example>
<?hard-pagebreak?> <?hard-pagebreak?>
<para><xref linkend="ImageCreateFullResponse"/> shows the <para><xref linkend="ImageCreateFullResponse"/> shows
headers and XML response returned by the JSON the headers and XML response returned by the JSON
request:</para> request:</para>
<example xml:id="ImageCreateFullResponse"> <example xml:id="ImageCreateFullResponse">
<title>XML response with headers</title> <title>XML response with headers</title>
@@ -620,17 +641,18 @@ X-Compute-Request-Id: req-ab05045a-452f-4b46-be0d-86494da02a2b
Server: Jetty(8.0.y.z-SNAPSHOT)</literallayout> Server: Jetty(8.0.y.z-SNAPSHOT)</literallayout>
<programlisting language="xml"><?db-font-size 70%?><xi:include href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/compute-api/src/v2/api_samples/server-post-resp.xml" parse="text"/></programlisting> <programlisting language="xml"><?db-font-size 70%?><xi:include href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/compute-api/src/v2/api_samples/server-post-resp.xml" parse="text"/></programlisting>
</example> </example>
<para>The following example shows an alternative method of <para>The following example shows an alternative
achieving the same result. The following request uses method of achieving the same result. The following
an URI extension of <literal>.xml</literal> instead of request uses an URI extension of
an <code>Accept</code> header to request an XML <literal>.xml</literal> instead of an
<code>Accept</code> header to request an XML
response.</para> response.</para>
<note> <note>
<para>The XML response is not shown.</para> <para>The XML response is not shown.</para>
</note> </note>
<example xml:id="diff_serialization"> <example xml:id="diff_serialization">
<title>JSON request with XML query extension for the <title>JSON request with XML query extension for
response</title> the response</title>
<literallayout role="monospace"><?db-font-size 70%?>POST /v2/010101/servers<emphasis role="bold">.xml</emphasis> HTTP/1.1 <literallayout role="monospace"><?db-font-size 70%?>POST /v2/010101/servers<emphasis role="bold">.xml</emphasis> HTTP/1.1
Host: servers.api.openstack.org Host: servers.api.openstack.org
Content-Type: application/json Content-Type: application/json
@@ -638,6 +660,7 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb</literallayout>
<programlisting language="json"><?db-font-size 70%?><xi:include href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/compute-api/src/v2/api_samples/server-post-req.json" parse="text"/></programlisting> <programlisting language="json"><?db-font-size 70%?><xi:include href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/compute-api/src/v2/api_samples/server-post-req.json" parse="text"/></programlisting>
</example> </example>
</section> </section>
</section>
<?hard-pagebreak?> <?hard-pagebreak?>
<section xml:id="LinksReferences"> <section xml:id="LinksReferences">
<title>Links and references</title> <title>Links and references</title>
@@ -962,20 +985,19 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb</literallayout>
<tr> <tr>
<td>maxTotalRAMSize</td> <td>maxTotalRAMSize</td>
<td>51200</td> <td>51200</td>
<td>Maximum total amount of <td>Maximum total amount of RAM (MB)</td>
RAM (MB)</td>
</tr> </tr>
<tr> <tr>
<td>maxServerMeta</td> <td>maxServerMeta</td>
<td>5</td> <td>5</td>
<td>Maximum number of metadata <td>Maximum number of metadata items
items associated with a server</td> associated with a server</td>
</tr> </tr>
<tr> <tr>
<td>maxImageMeta</td> <td>maxImageMeta</td>
<td>5</td> <td>5</td>
<td>Maximum number of metadata <td>Maximum number of metadata items
items associated with an Image</td> associated with an Image</td>
</tr> </tr>
<tr> <tr>
<td>maxPersonality</td> <td>maxPersonality</td>
@@ -987,8 +1009,8 @@ X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb</literallayout>
<tr> <tr>
<td>maxPersonalitySize</td> <td>maxPersonalitySize</td>
<td>10240</td> <td>10240</td>
<td>The maximum size, in <td>The maximum size, in bytes, for each
bytes, for each personality file</td> personality file</td>
</tr> </tr>
</tbody> </tbody>
</table> </table>
@@ -1575,6 +1597,13 @@ Host: servers.api.openstack.org/v2/</literallayout>
<emphasis>per account</emphasis> and is <emphasis>per account</emphasis> and is
not globally unique.</para> not globally unique.</para>
</note> </note>
<!--<wadl:resources
xmlns:wadl="http://wadl.dev.java.net/2009/02">
<wadl:resource
href="v2/wadl/os-compute-2.wadl#Servers">
<wadl:method href="#listServers"/>
</wadl:resource>
</wadl:resources>-->
<wadl:resources <wadl:resources
xmlns:wadl="http://wadl.dev.java.net/2009/02"> xmlns:wadl="http://wadl.dev.java.net/2009/02">
<wadl:resource <wadl:resource
@@ -1902,8 +1931,9 @@ Host: servers.api.openstack.org/v2/</literallayout>
<?hard-pagebreak?> <?hard-pagebreak?>
<section xml:id="NetworksSection"> <section xml:id="NetworksSection">
<title>Networks</title> <title>Networks</title>
<para>Using the network API you can create, update, delete and <para>Using the network API you can create, update, delete
show networks, ports and subnets. A few examples are given below.</para> and show networks, ports and subnets. A few examples
are given below.</para>
<table rules="all" xml:id="NetworkMethods-d1e5091"> <table rules="all" xml:id="NetworkMethods-d1e5091">
<caption>Get all networks</caption> <caption>Get all networks</caption>
<thead> <thead>
@@ -1956,8 +1986,8 @@ Host: servers.api.openstack.org/v2/</literallayout>
<tr> <tr>
<td>fixed_ip</td> <td>fixed_ip</td>
<td>IPv4</td> <td>IPv4</td>
<td>The IP address to assign to <td>The IP address to assign to the
the interface.</td> interface.</td>
</tr> </tr>
<tr> <tr>
<td>port</td> <td>port</td>