<?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>