ed4f3c4db9
Point to WADL files that generate the API Reference
page so that the method descriptions and request
and response parameters are consistent between
these two docs:
http://api.openstack.org/api-ref-objectstorage.html
(API Reference page for Object Storage)
http://docs.openstack.org/api/openstack-object-storage/1.0/
(API Reference (or spec) for Object Storage)
Add descriptions of ACLs, FormPOST, TempURLs,
StaticWeb, Bulk Upload, Bulk Delete, the OPTIONS operation
(though this is implicit in CORS support)
Validate all code examples
Remove duplication.
Co-Author: Donagh McCabe
Closes-Bug: #1187119
Closes-Bug: #1214139
Closes-Bug: #1074198
Partial-Bug: #1255770
Change-Id: I94054b046a94260ba8825bdb42439adfcaf9fdce
author: diane fleming
212 lines
8.1 KiB
XML
212 lines
8.1 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE section [
|
|
<!-- Some useful entities borrowed from HTML -->
|
|
<!ENTITY ndash "–">
|
|
<!ENTITY mdash "—">
|
|
<!ENTITY hellip "…">
|
|
<!ENTITY plusmn "±">
|
|
|
|
<!-- Useful for describing APIs -->
|
|
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
|
|
<!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
|
|
<!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
|
|
<!ENTITY DELETE '<command xmlns="http://docbook.org/ns/docbook">DELETE</command>'>
|
|
|
|
<!ENTITY CHECK '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
|
|
<imageobject>
|
|
<imagedata fileref="figures/Check_mark_23x20_02.svg"
|
|
format="SVG" scale="60"/>
|
|
</imageobject>
|
|
</inlinemediaobject>'>
|
|
|
|
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
|
|
<imageobject>
|
|
<imagedata fileref="figures/Arrow_east.svg"
|
|
format="SVG" scale="60"/>
|
|
</imageobject>
|
|
</inlinemediaobject>'>
|
|
]>
|
|
<section xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
|
|
xml:id="curl">
|
|
<title>cURL commands</title>
|
|
<para>cURL is a command-line tool that you can use to interact
|
|
with REST interfaces. cURL lets you to transmit and receive
|
|
HTTP requests and responses from the command line or a shell
|
|
script, which enables you to work with the API directly. It is
|
|
available for Linux distributions, Mac OS X, and Windows. For
|
|
information about cURL, see <link
|
|
xlink:href="http://curl.haxx.se/"
|
|
>http://curl.haxx.se/</link>.</para>
|
|
<para>To run the cURL request examples shown in this guide, copy
|
|
each example from the HTML version of this guide directly to
|
|
the command line or a script.</para>
|
|
<para>Before you can run these examples, you must set environment
|
|
variables. See <xref linkend="env-vars"/>.</para>
|
|
<para>This example cURL command shows account details and lists
|
|
containers in the account.</para>
|
|
<screen><prompt>#</prompt> <userinput>curl -i $publicURL?format=json \
|
|
-X GET -H "X-Auth-Token: $token"</userinput></screen>
|
|
<screen><computeroutput>HTTP/1.1 200 OK
|
|
Content-Length: 96
|
|
X-Account-Object-Count: 1
|
|
X-Timestamp: 1389453423.35964
|
|
X-Account-Meta-Subject: Literature
|
|
X-Account-Bytes-Used: 14
|
|
X-Account-Container-Count: 2
|
|
Content-Type: application/json; charset=utf-8
|
|
Accept-Ranges: bytes
|
|
X-Trans-Id: tx274a77a8975c4a66aeb24-0052d95365
|
|
Date: Fri, 17 Jan 2014 15:59:33 GMT</computeroutput>
|
|
</screen>
|
|
<para>The response, in JSON format, is:</para>
|
|
<programlisting language="json">[
|
|
{
|
|
"count":0,
|
|
"bytes":0,
|
|
"name":"janeausten"
|
|
},
|
|
{
|
|
"count":1,
|
|
"bytes":14,
|
|
"name":"marktwain"
|
|
}
|
|
]</programlisting>
|
|
<note>
|
|
<para>The carriage returns in the cURL request examples are
|
|
escaped with a backslash (<literal>\</literal>) character.
|
|
The escape character allows continuation of the command
|
|
across multiple lines. However, do not include the escape
|
|
character in the JSON or XML request body within the cURL
|
|
command.</para>
|
|
</note>
|
|
<para>The cURL examples in this guide use the following
|
|
command-line options:</para>
|
|
<table xml:id="curl_options" rules="all" width="75%">
|
|
<caption>cURL command-line options</caption>
|
|
<thead>
|
|
<tr>
|
|
<th>Option</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>
|
|
<option>-d</option>
|
|
</td>
|
|
<td>
|
|
<para>Sends the specified data in a &POST; request
|
|
to the HTTP server. Use this option to send a
|
|
JSON or XML request body to the server.</para>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<option>-H</option>
|
|
</td>
|
|
<td>
|
|
<para>Specifies an extra HTTP header in the
|
|
request. You can specify any number of extra
|
|
headers. Precede each header with the
|
|
<option>-H</option> option.</para>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<option>-i</option>
|
|
</td>
|
|
<td>
|
|
<para>Includes the HTTP response headers in the
|
|
output.</para>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<option>-s</option>
|
|
</td>
|
|
<td>
|
|
<para>Silent or quiet mode. Does not show progress
|
|
or error messages. Makes cURL mute.</para>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<option>-T</option>
|
|
</td>
|
|
<td>
|
|
<para>Transfers the specified local file to the
|
|
remote URL.</para>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<option>-X</option>
|
|
</td>
|
|
<td>
|
|
<para>Specifies the request method to use when
|
|
communicating with the HTTP server. The
|
|
specified request is used instead of the
|
|
default method, which is &GET;.</para>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<note xml:id="json_tool">
|
|
<title>json.tool</title>
|
|
<para>For commands that return a response, you can append the
|
|
following code to the command to call the json.tool to
|
|
pretty-print output:</para>
|
|
<programlisting language="bash" role="gutter: false">| python -m json.tool</programlisting>
|
|
<para>To use the <filename>json.tool</filename>, import the
|
|
<literal>json</literal> module. For information about
|
|
the <filename>json.tool</filename>, see <link
|
|
xlink:href="http://docs.python.org/2/library/json.html"
|
|
>json — JSON encoder and decoder</link>.</para>
|
|
<para>If you run a Python version older than 2.6, import the
|
|
<literal>simplejson</literal> module and use the
|
|
<filename>simplejson.tool</filename>. For information
|
|
about the <filename>simple.json</filename> tool, see <link
|
|
xlink:href="http://simplejson.googlecode.com/svn/tags/simplejson-2.0.9/docs/index.html"
|
|
>simplejson — JSON encoder and decoder</link>.</para>
|
|
<para>If you do not want to pretty-print JSON output, omit
|
|
this code.</para>
|
|
</note>
|
|
<section xml:id="curl_summary_xml">
|
|
<title>Example of an XML response</title>
|
|
<para>To request an XML response, append the
|
|
<literal>format=xml</literal> query parameter to the
|
|
request.</para>
|
|
<para>This example cURL command shows account information and
|
|
list containers in the account, and asks for the response
|
|
in XML:</para>
|
|
<screen><prompt>#</prompt> <userinput>curl -i $publicURL?format=xml \
|
|
-X GET -H "X-Auth-Token: $token"</userinput></screen>
|
|
<screen><computeroutput>HTTP/1.1 200 OK
|
|
Content-Length: 262
|
|
X-Account-Object-Count: 1
|
|
X-Timestamp: 1389453423.35964
|
|
X-Account-Meta-Subject: Literature
|
|
X-Account-Bytes-Used: 14
|
|
X-Account-Container-Count: 2
|
|
Content-Type: application/xml; charset=utf-8
|
|
Accept-Ranges: bytes
|
|
X-Trans-Id: tx69f60bc9f7634a01988e6-0052d9544b
|
|
Date: Fri, 17 Jan 2014 16:03:23 GMT</computeroutput></screen>
|
|
<programlisting language="xml"><?xml version="1.0" encoding="UTF-8"?>
|
|
<account name="my_account">
|
|
<container>
|
|
<name>janeausten</name>
|
|
<count>0</count>
|
|
<bytes>0</bytes>
|
|
</container>
|
|
<container>
|
|
<name>marktwain</name>
|
|
<count>1</count>
|
|
<bytes>14</bytes>
|
|
</container>
|
|
</account</programlisting>
|
|
</section>
|
|
</section>
|