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
commit 657292543f
2 changed files with 117 additions and 87 deletions
Show Stats 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>

202
v2/bk_compute_api_ref_v2.xml
View File

@ -547,96 +547,119 @@
</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>
<listitem> </section>
<para><code>Accept</code> header. The syntax for <section xml:id="response-format">
the <code>Accept</code> header is: <title>Response format</title>
<programlisting>Accept: application/<parameter>format</parameter></programlisting></para> <para>Use one of the following methods to specify the
<para>Where <parameter>format</parameter> is response format:</para>
either <constant>json</constant> or <variablelist>
<constant>xml</constant>, the default <varlistentry>
format is <literal>json</literal>.</para> <term><code>Accept</code> header</term>
</listitem> <listitem>
<listitem> <para>The syntax for the
<para>Query extension. Add an <code>Accept</code> header
<literal>.xml</literal> or is:</para>
<literal>.json</literal> extension to the <programlisting>Accept: application/<replaceable>FORMAT</replaceable></programlisting>
request URI. For example, the <para>Where
<literal>.xml</literal> extension in the <replaceable>FORMAT</replaceable>
following URI request specifies that the is either <literal>json</literal> or
response body is returned in XML format: <literal>xml</literal>. The default
<literallayout role="monospace">&POST; /v2/010101/servers.xml</literallayout></para> format is
</listitem> <literal>json</literal>.</para>
</itemizedlist> </listitem>
<para>If you do not specify a response format, JSON is the </varlistentry>
default.</para> <varlistentry>
<para>If you specify conflicting formats in the <term>Query extension</term>
<code>Accept</code> header and the query <listitem>
extension, the format specified in the query extension <para>Add an <literal>.xml</literal> or
takes precedence. For example, if the query extension <literal>.json</literal> extension
is <literal>.xml</literal> and the <code>Accept</code> to the request URI. For example, the
header specifies <literal>application/json</literal>, <literal>.xml</literal> extension
the response is returned in XML format.</para> in the following list servers URI
<para>You can serialize a response in a different format request specifies that the response
from the request format. <xref linkend="JSON_req"/> body is to be returned in XML
and <xref linkend="ImageCreateFullResponse"/> show a format:</para>
request body in JSON format and a response body in XML <literallayout role="monospace">&GET; <replaceable>publicURL</replaceable>/servers.xml</literallayout>
format.</para> </listitem>
<example xml:id="JSON_req"> </varlistentry>
<title>JSON request with headers</title> </variablelist>
<literallayout role="monospace"><?db-font-size 70%?>POST /v2/010101/servers HTTP/1.1 <para>If you do not specify a response format, JSON is
the default.</para>
<para>If the <code>Accept</code> header and the query
extension specify conflicting formats, the format
specified in the query extension takes precedence.
For example, if the query extension is
<literal>.xml</literal> and the
<code>Accept</code> header specifies
<literal>application/json</literal>, the
response is returned in XML format.</para>
</section>
<section xml:id="request-response-examples">
<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">
<title>JSON request with headers</title>
<literallayout role="monospace"><?db-font-size 70%?>POST /v2/010101/servers HTTP/1.1
Host: servers.api.openstack.org Host: servers.api.openstack.org
Content-Type: application/json Content-Type: application/json
Accept: application/xml Accept: application/xml
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb</literallayout> 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>
<literallayout role="monospace"><?db-font-size 70%?>HTTP/1.1 202 Accepted <literallayout role="monospace"><?db-font-size 70%?>HTTP/1.1 202 Accepted
Date: Mon, 23 Jul 2012 20:24:48 GMT Date: Mon, 23 Jul 2012 20:24:48 GMT
Content-Length: 582 Content-Length: 582
Location: https://servers.api.openstack.org/v2/010101/servers/06dba123-2c7e-4639-bea0-09fbe219b056 Location: https://servers.api.openstack.org/v2/010101/servers/06dba123-2c7e-4639-bea0-09fbe219b056
Content-Type: application/xml Content-Type: application/xml
X-Compute-Request-Id: req-ab05045a-452f-4b46-be0d-86494da02a2b 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
response.</para> <code>Accept</code> header to request an XML
<note> response.</para>
<para>The XML response is not shown.</para> <note>
</note> <para>The XML response is not shown.</para>
<example xml:id="diff_serialization"> </note>
<title>JSON request with XML query extension for the <example xml:id="diff_serialization">
response</title> <title>JSON request with XML query extension for
<literallayout role="monospace"><?db-font-size 70%?>POST /v2/010101/servers<emphasis role="bold">.xml</emphasis> HTTP/1.1 the response</title>
<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
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb</literallayout> 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">
@ -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>