<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book [
        <!-- Some useful entities borrowed from HTML -->
        <!ENTITY ndash  "&#x2013;">
        <!ENTITY mdash  "&#x2014;">
        <!ENTITY hellip "&#x2026;">

        <!-- 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>'>

        <!-- changing authentication endpoints; define entities for US & UK rather than maintaining in text -->
        <!ENTITY ENDPOINT-US "https://identity.api.rackspacecloud.com/v1.1/">
        <!ENTITY ENDPOINT-UK "https://lon.identity.api.rackspacecloud.com/v1.1/">
        <!ENTITY ENDPOINT-US-20 "https://identity.api.rackspacecloud.com/v2.0/">
        <!ENTITY ENDPOINT-UK-20 "https://lon.identity.api.rackspacecloud.com/v2.0/">

        <!ENTITY CHECK  '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
                 <imageobject>
                  <imagedata fileref="img/Check_mark_23x20_02.svg"
                             format="SVG" scale="60"/>
                </imageobject>
              </inlinemediaobject>'>

        <!ENTITY ARROW  '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
                 <imageobject>
                  <imagedata fileref="img/Arrow_east.svg"
                             format="SVG" scale="60"/>
                </imageobject>
              </inlinemediaobject>'>
]>
<book xmlns="http://docbook.org/ns/docbook"
    xmlns:xlink="http://www.w3.org/1999/xlink"
    xmlns:xi="http://www.w3.org/2001/XInclude"
    xmlns:svg="http://www.w3.org/2000/svg"
    xmlns:m="http://www.w3.org/1998/Math/MathML"
    xmlns:html="http://www.w3.org/1999/xhtml" xml:id="cdb-devguide"
    version="5.0">

    <?rax title.font.size="35px" subtitle.font.size="20px"?>
    <title>OpenStack Cloud Databases Developer Guide</title>
    <titleabbrev>OpenStack Cloud Databases Developer
        Guide</titleabbrev>
    <info>
        <author>
            <personname>
                <firstname/>
                <surname/>
            </personname>
            <affiliation>
                <orgname>OpenStack LLC</orgname>
            </affiliation>
        </author>
        <copyright>
            <year>2010</year>
            <year>2011</year>
            <year>2012</year>
            <year>2013</year>
            <holder>OpenStack LLC</holder>
        </copyright>
        <releaseinfo>API v1.0</releaseinfo>
        <productname>OpenStack Cloud Databases</productname>
        <pubdate/>
        <legalnotice role="apache2">
            <annotation>
                <remark>Copyright details are filled in by the
                    template.</remark>
            </annotation>
        </legalnotice>
        <abstract>
            <para>This document is intended for software developers
                interested in developing applications using the
                OpenStack Cloud Databases Application Programming
                Interface (<abbrev>API</abbrev>).</para>
        </abstract>

        <revhistory>
            <revision>
                <date>2013-05-02</date>
                <revdescription>
                    <itemizedlist spacing="compact">
                        <listitem>
                            <para>This document is for the initial
                                OpenStack review.</para>
                        </listitem>
                    </itemizedlist>
                </revdescription>
            </revision>
        </revhistory>

        <cover>
            <para>this is a placeholder for the front cover</para>
        </cover>
        <cover>
            <para>this is a placeholder for the back cover</para>
        </cover>
        <raxm:metadata
            xmlns:raxm="http://docs.rackspace.com/api/metadata">
            <raxm:displayname>API Developer Guide</raxm:displayname>
            <raxm:product version="v1.0">cdb</raxm:product>
            <raxm:priority>20</raxm:priority>
        </raxm:metadata>
    </info>
    <chapter xml:id="overview">
        <title>Overview</title>
        <para>OpenStack Cloud Databases is an OpenStack-based MySQL
            relational database service that allows customers to
            easily provision database instances of varying virtual
            resource sizes without the need to maintain and/or update
            MySQL. Interactions with Cloud Databases occur
            programmatically via the Cloud Databases API as described
            in this developer guide.</para>
        <note>
            <para>OpenStack recommends that Cloud Databases users back
                up their data using <emphasis role="bold"
                    >mysqldump</emphasis> until backups are supported
                in Cloud Databases.</para>
        </note>
        <para>The following figure shows an overview of Cloud
            Databases Infrastructure:</para>
        <informalfigure>
            <mediaobject>
                <imageobject>
                    <imagedata
                        fileref="images/Cloud_DB_Infographic-1.svg"
                        contentwidth="6in"/>
                </imageobject>
            </mediaobject>
        </informalfigure>
        <remark security="reviewer">Reviewer: need to edit graphic
            above so it says "The Cloud" rather than "The Rackspace
            Cloud".</remark>
        <?hard-pagebreak?>
        <section xml:id="Intended_Audience-d1e122">
            <title>Intended Audience</title>
            <para>This Guide is intended to assist software developers
                who want to develop applications using the Cloud
                Databases API. It assumes the reader has a general
                understanding of databases and is familiar
                with:</para>
            <itemizedlist spacing="compact">
                <listitem>
                    <para>ReSTful web services</para>
                </listitem>
                <listitem>
                    <para>HTTP/1.1 conventions</para>
                </listitem>
                <listitem>
                    <para>JSON data serialization
                        format</para>
                </listitem>
            </itemizedlist>
        </section>
        <?hard-pagebreak?>
        <section xml:id="Document_Change_History-d1e166">
            <title>Document Change History</title>
            <para>This version of the Developer Guide replaces and
                obsoletes all previous versions. The most recent
                changes are described in the table below:</para>
            <?rax revhistory?>
        </section>
        <section xml:id="Additional_Resources-d1e532">
            <title>Additional Resources</title>
            <para>You can download the most current versions of this
                and other API-related documents from <link
                    xlink:href="http://docs.openstack.org/"
                    >http://docs.openstack.org/</link>.</para>
            <para>We welcome feedback, comments, and bug reports at
                    <link
                    xlink:href="https://bugs.launchpad.net/reddwarf"
                    >https://bugs.launchpad.net/reddwarf</link>.</para>
            <para>This API uses standard HTTP 1.1 response codes as
                documented at: <link
                    xlink:href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html"
                    >http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html</link>.</para>
        </section>
        <?hard-pagebreak?>
    </chapter>

    <chapter xml:id="Concepts-d1e563">
        <title>Concepts</title>
        <?dbhtml stop-chunking?>
        <para>To use the Cloud Databases API effectively, you should
            understand several key concepts:</para>
        <section xml:id="DatabaseInstance-d1e588">
            <title>Database Instance</title>
            <para>A database instance is an isolated MySQL instance in
                a single tenant environment on a shared physical host
                machine.</para>
            <remark security="writeronly">Writer: once we support
                MSSQL, we need to describe here what is used for MSSQL
                in place of database instance.</remark>
        </section>
        <section xml:id="Database">
            <title>Database</title>
            <para>A MySQL database within a database instance.</para>
            <remark security="writeronly">Writer: once we support
                MSSQL, we need to modify the wording here, such as:
                The actual database, whether it is in MySQL or
                MSSQL.</remark>
        </section>
        <section xml:id="Flavor">
            <title>Flavor</title>
            <para>A flavor is an available hardware configuration for
                a database instance. Each flavor has a unique
                combination of memory capacity and priority for CPU
                time.</para>
        </section>
        <section xml:id="Volume">
            <title>Volume</title>
            <para>A volume is user-specified storage that contains the
                MySQL data directory. Volumes are automatically
                provisioned on shared Internet Small Computer System
                Interface (iSCSI) storage area networks (SAN) that
                provide for increased performance, scalability,
                availability and manageability. Applications with high
                I/O demands are performance optimized and data is
                protected through both local and network RAID-10.
                Additionally, network RAID provides synchronous
                replication of volumes with automatic failover and
                load balancing across available storage
                clusters.</para>
        </section>
    </chapter>
    <chapter xml:id="General_API_Information-d1e633">
        <title>General API Information</title>
        <para>The Cloud Databases API is implemented using a ReSTful
            web service interface. Like other cloud products, the
            Database Service shares a common token-based
            authentication system that allows seamless access between
            products and services.</para>
        <note>
            <para>All requests to authenticate against and operate the
                service are performed using SSL over HTTP (HTTPS) on
                TCP port 443.</para>
        </note>
        <section xml:id="Authentication-d1e647">
            <title>Authentication</title>
            <para>Each HTTP request against the Cloud Database service
                requires the inclusion of specific authentication
                credentials. A single deployment may support multiple
                authentication schemes (OAuth, Basic Auth, Token). The
                authentication scheme used is determined by the
                provider of the Cloud Database service. Please contact
                your provider to determine the best way to
                authenticate against this API.</para>
            <note>
                <para>Some authentication schemes may require that the
                    API operate using SSL over HTTP (HTTPS).</para>
            </note>
        </section>
        <section xml:id="DB_service_versions">
            <title>Cloud Databases Service Versions</title>
            <para>The Cloud Databases version defines the contract and
                build information for the API.</para>
            <section xml:id="Contract_Version-d1e825">
                <title>Contract Version</title>
                <para>The contract version denotes the data model and
                    behavior that the API supports. The requested
                    contract version is included in all request URLs.
                    Different contract versions of the API may be
                    available at any given time and are not guaranteed
                    to be compatible with one another.</para>
                <example>
                    <title>Example Request URL (contract version in
                            <emphasis role="strong"
                        >bold</emphasis>)</title>
                    <programlisting>https://ord.databases.api.rackspacecloud.com/<emphasis role="strong">v1.0</emphasis>/1234</programlisting>
                </example>
                <note>
                    <para>This document pertains to contract version
                        1.0.</para>
                </note>

            </section>
            <section xml:id="API_Version_Headers-d1e855">
                <title>API Version</title>
                <para>The API List Versions call is available to show
                    the current API version as well as information
                    about all versions of the API. Refer to <xref
                        linkend="API_Versions"/> for details.</para>
            </section>
        </section>
        <?hard-pagebreak?>
        <section xml:id="datetimeformat">
            <title>Date/Time Format</title>
            <para>The Database Service uses an ISO-8601 compliant date
                format for the display and consumption of date/time
                values.</para>
            <para>The system timezone is in UTC. MySQL converts
                TIMESTAMP values from the current time zone to UTC for
                storage, and back from UTC to the current time zone
                for retrieval. This does not occur for other types,
                such as DATETIME.</para>
            <example>
                <title>DB Service Date/Time Format</title>
                <programlisting>yyyy-MM-dd'T'HH:mm:ss.SSSZ</programlisting>
                <para>See the table below for a description of the
                    date/time format codes.</para>
                <para>May 19th, 2011 at 8:07:08 AM, GMT-5 would have
                    the following format:</para>
                <programlisting>2011-05-19T08:07:08-05:00</programlisting>
            </example>
            <table rules="all">
                <caption>Explanation of Date/Time Format
                    Codes</caption>
                <thead>
                    <tr>
                        <td>Code</td>
                        <td>Description</td>
                    </tr>
                </thead>
                <tbody>
                    <tr>
                        <td>yyyy</td>
                        <td>Four digit year</td>
                    </tr>
                    <tr>
                        <td>MM</td>
                        <td>Two digit month</td>
                    </tr>
                    <tr>
                        <td>dd</td>
                        <td>Two digit day of month</td>
                    </tr>
                    <tr>
                        <td>T</td>
                        <td>Separator for date/time</td>
                    </tr>
                    <tr>
                        <td>HH</td>
                        <td>Two digit hour of day (00-23)</td>
                    </tr>
                    <tr>
                        <td>mm</td>
                        <td>Two digit minutes of hour</td>
                    </tr>
                    <tr>
                        <td>ss</td>
                        <td>Two digit seconds of the minute</td>
                    </tr>
                    <tr>
                        <td>SSS</td>
                        <td>Three digit milliseconds of the
                            second</td>
                    </tr>
                    <tr>
                        <td>Z</td>
                        <td>RFC-822 timezone</td>
                    </tr>
                </tbody>
            </table>

        </section>
        <section xml:id="pagination">
            <title>Pagination</title>
            <para>To reduce load on the service, list operations
                return a maximum of 20 items at a time. This is
                referred to as <emphasis>pagination</emphasis>. Cloud
                Databases has separate paging limits for instances,
                databases, and users, which are currently all set to
                20. If a request supplies no limit or one that exceeds
                the configured default limit, the default is used
                instead.</para>
            <para>Pagination provides the ability to limit the size of
                the returned data as well as retrieve a specified
                subset of a large data set. Pagination has two key
                concepts: limit and marker. <emphasis>Limit</emphasis>
                is the restriction on the maximum number of items for
                that type that can be returned.
                    <emphasis>Marker</emphasis> is the ID of the last
                item in the previous list returned. The ID is the UUID
                in the case of instances, and the name in the case of
                databases and users. For example, a query could
                request the next 10 instances after the instance
                "1234" as follows:
                    <code>?limit=10&amp;marker=1234</code>. Items are
                displayed sorted by ID.</para>
            <para>Pagination applies only to the calls listed in the
                following table:</para>
            <informaltable rules="all">
                <thead>
                    <tr align="center">
                        <td colspan="1">Verb</td>
                        <td colspan="2">URI</td>
                        <td colspan="3">Description</td>
                    </tr>
                </thead>
                <tbody>
                    <tr>
                        <td colspan="1">&GET;</td>
                        <td colspan="2">/instances/</td>
                        <td colspan="3">Lists the status and
                            information for all database
                            instances.</td>
                    </tr>
                    <tr>
                        <td colspan="1">&GET;</td>
                        <td colspan="2">
                            /instances/{instanceId}/databases</td>
                        <td colspan="3">Lists databases for the
                            specified instance.</td>
                    </tr>
                    <tr>
                        <td colspan="1">&GET;</td>
                        <td colspan="2">
                            /instances/{instanceId}/users</td>
                        <td colspan="3">Lists the users in the
                            specified database instance.</td>
                    </tr>
                </tbody>
            </informaltable>
            <para>If the content returned by a call is paginated, the
                response includes a structured link much like an
                instance item's links, with the basic structure
                    <code>{"href": "&lt;url>", "rel": "next"}</code>.
                Any response that is truncated by pagination will have
                a <emphasis>next</emphasis> link, which points to the
                next item in the collection. If there are no more
                items, no <emphasis>next</emphasis> link is
                returned.</para>
            <para>See the examples of paged List Instances calls that
                follow.</para>
            <remark security="reviewer">Reviewer: Need new examples
                that show OpenStack host.</remark>
            <example>
                <title>List Instances Paged Request: JSON</title>
                <?dbfo keep-together="always"?>
                <programlisting language="json"><xi:include href="samples/db-instances-index-pagination-request-json.txt" parse="text"/></programlisting>
            </example>
            <para>Notice that the paged request examples above set the
                limit to 2 (<code>?limit=2</code>), so the responses
                that follow each show 2 instances and return a
                    <emphasis>marker</emphasis> set to the UUID of the
                last item in the returned list
                    (<code>?marker=4137d6a4-03b7-4b66-b0ef-8c7c35c470d3</code>).
                Also a link is provided to retrieve the next 2 results
                    (<code>limit=2</code>) in the link element
                identified by <code>"rel":"next"</code>:</para>
            <example>
                <title>List Instances Paged Response: JSON</title>
                <?dbfo keep-together="always"?>
                <literallayout>HTTP/1.1 200 OK
Content-Type: application/json
Via: 1.1 Repose (Repose/2.6.7)
Content-Length: 1172
Date: Mon, 18 Mar 2013 19:09:17 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)</literallayout>
<programlisting language="json"><xi:include href="samples/db-instances-index-pagination-response.json" parse="text"/></programlisting>
            </example>
        </section>
        <section xml:id="DB_faults">
            <title>Faults</title>
            <para>When an error occurs, the Database Service returns a
                fault object containing an HTTP error response code
                that denotes the type of error. In the body of the
                response, the system will return additional
                information about the fault.</para>
            <para>The following table lists possible fault types with
                their associated error codes and descriptions.</para>
            <informaltable rules="all">
                <thead>
                    <tr align="center">
                        <td colspan="2">Fault Type</td>
                        <td colspan="1">Associated Error Code</td>
                        <td colspan="3">Description</td>
                    </tr>
                </thead>
                <tbody>
                    <tr>
                        <td colspan="2"><code>badRequest</code></td>
                        <td colspan="1">400</td>
                        <td colspan="3">There was one or more errors
                            in the user request.</td>
                    </tr>
                    <tr>
                        <td colspan="2"><code>unauthorized</code></td>
                        <td colspan="1">401</td>
                        <td colspan="3">The supplied token is not
                            authorized to access the resources, either
                            it's expired or invalid.</td>
                    </tr>
                    <tr>
                        <td colspan="2"><code>forbidden</code></td>
                        <td colspan="1">403</td>
                        <td colspan="3">Access to the requested
                            resource was denied.</td>
                    </tr>
                    <tr>
                        <td colspan="2"><code>itemNotFound</code></td>
                        <td colspan="1">404</td>
                        <td colspan="3">The back-end services did not
                            find anything matching the
                            Request-URI.</td>
                    </tr>
                    <tr>
                        <td colspan="2"><code>badMethod</code></td>
                        <td colspan="1">405</td>
                        <td colspan="3">The request method is not
                            allowed for this resource.</td>
                    </tr>
                    <tr>
                        <td colspan="2"><code>overLimit</code></td>
                        <td colspan="1">413</td>
                        <td colspan="3">Either the number of entities
                            in the request is larger than allowed
                            limits, or the user has exceeded allowable
                            request rate limits. See the
                                <code>details</code> element for more
                            specifics. Contact support if you think
                            you need higher request rate limits.</td>
                    </tr>
                    <tr>
                        <td colspan="2"><code>badMediaType</code></td>
                        <td colspan="1">415</td>
                        <td colspan="3">The requested content type is
                            not supported by this service.</td>
                    </tr>
                    <tr>
                        <td colspan="2"
                                ><code>unprocessableEntity</code></td>
                        <td colspan="1">422</td>
                        <td colspan="3">The requested resource could
                            not be processed on at the moment.</td>
                    </tr>
                    <tr>
                        <td colspan="2"
                            ><code>instanceFault</code></td>
                        <td colspan="1">500</td>
                        <td colspan="3">This is a generic server error
                            and the message contains the reason for
                            the error. This error could wrap several
                            error messages and is a catch all.</td>
                    </tr>
                    <tr>
                        <td colspan="2"
                            ><code>notImplemented</code></td>
                        <td colspan="1">501</td>
                        <td colspan="3">The requested method or
                            resource is not implemented.</td>
                    </tr>
                    <tr>
                        <td colspan="2"
                                ><code>serviceUnavailable</code></td>
                        <td colspan="1">503</td>
                        <td colspan="3">The Database Service is not
                            available.</td>
                    </tr>
                </tbody>
            </informaltable>
            <para>The following two <code>instanceFault</code>
                examples show errors when the server has erred or
                cannot perform the requested operation:</para>

            <example>
                <title>Example Fault Response: JSON</title>
                <?dbfo keep-together="always"?>
                <literallayout>HTTP/1.1 500 Internal Server Error
Content-Length: 120
Content-Type: application/json; charset=UTF-8
Date: Tue, 29 Nov 2011 00:33:48 GMT</literallayout>
<programlisting language="json"><xi:include href="samples/db-faults-instanceFault.json" parse="text"/></programlisting>
            </example>
            <para>The error code (<code>code</code>) is returned in
                the body of the response for convenience. The
                    <code>message</code> element returns a
                human-readable message that is appropriate for display
                to the end user. The <code>details</code> element is
                optional and may contain information that is useful
                for tracking down an error, such as a stack trace. The
                    <code>details</code> element may or may not be
                appropriate for display to an end user, depending on
                the role and experience of the end user.</para>
            <para>The fault's root element (for example,
                    <code>instanceFault</code>) may change depending
                on the type of error.</para>
            <para><?rax-fo keep-with-next?>The following two
                    <code>badRequest</code> examples show errors when
                the volume size is invalid:</para>
            <example>
                <title>Example badRequest Fault on Volume Size Errors:
                    JSON</title>
                <?dbfo keep-together="always"?>
                <literallayout>HTTP/1.1 400 None
Content-Length: 120
Content-Type: application/json; charset=UTF-8
Date: Tue, 29 Nov 2011 00:33:48 GMT</literallayout>
<programlisting language="json"><xi:include href="samples/db-faults-badRequest.json" parse="text"/></programlisting>
            </example>
            <para>The next two examples show <code>itemNotFound</code>
                errors:</para>
            <example>
                <title>Example itemNotFound Fault: JSON</title>
                <?dbfo keep-together="always"?>
                <literallayout>HTTP/1.1 404 Not Found
Content-Length: 78
Content-Type: application/json; charset=UTF-8
Date: Tue, 29 Nov 2011 00:35:24 GMT</literallayout>
<programlisting language="json"><xi:include href="samples/db-faults-itemNotFound.json" parse="text"/></programlisting>
            </example>
            <section xml:id="synchro_vs_async_faults">
                <title>Synchronous Versus Asynchronous
                    Faults<?sbr?></title>
                <para><emphasis>Synchronous</emphasis> faults occur at
                    request time. When a synchronous fault occurs, the
                    fault contains an HTTP error response code, a
                    human readable message, and optional details about
                    the error. The following Database API calls are
                    synchronous and may produce synchronous
                        faults:<itemizedlist spacing="compact">
                        <listitem>
                            <para>List Users</para>
                        </listitem>
                        <listitem>
                            <para>List Instances</para>
                        </listitem>
                        <listitem>
                            <para>List Instance Details by ID</para>
                        </listitem>
                        <listitem>
                            <para>List Databases</para>
                        </listitem>
                        <listitem>
                            <para>Enable Root User</para>
                        </listitem>
                        <listitem>
                            <para>List Root-Enabled Status</para>
                        </listitem>
                        <listitem>
                            <para>List Flavors</para>
                        </listitem>
                        <listitem>
                            <para>List Versions</para>
                        </listitem>
                        <listitem>
                            <para>List Version Details</para>
                        </listitem>
                    </itemizedlist></para>
                <para><emphasis>Asynchronous</emphasis> faults occur
                    in the background while an instance, database, or
                    user is being built or an instance is executing an
                    action. When an asynchronous fault occurs, the
                    system places the instance, database, or user in
                    an ERROR state and embeds the fault in the
                    offending instance, database, or user. When an
                    asynchronous fault occurs, the fault contains an
                    HTTP error response code, a human readable
                    message, and optional details about the error. The
                    following Database API calls are asynchronous and
                    may produce asynchronous faults:</para><itemizedlist
                        spacing="compact">
                        <listitem>
                            <para>Create Instance</para>
                        </listitem>
                        <listitem>
                            <para>Delete Instance</para>
                        </listitem>
                        <listitem>
                            <para>Create Database</para>
                        </listitem>
                        <listitem>
                            <para>Delete Database</para>
                        </listitem>
                        <listitem>
                            <para>Create User</para>
                        </listitem>
                        <listitem>
                            <para>Delete User</para>
                        </listitem>
                        <listitem>
                            <para>Resize Volume</para>
                        </listitem>
                        <listitem>
                            <para>Resize Instance</para>
                        </listitem>
                        <listitem>
                            <para>Restart Instance</para>
                        </listitem>
                    </itemizedlist>
                    <note>
                        <para>Note that an asynchronous operation, if
                            it fails, may not give the user an error,
                            and the operation can error out without a
                            failure notification.</para>
                    </note>
            </section>
        </section>
        <section xml:id="database_instance_status">
            <title>Database Instance Status</title>
            <para><?rax-fo keep-with-next?>When making an API call to
                create, list, or delete database instance(s), the
                following database instance status values are
                possible:</para>
            <itemizedlist spacing="compact">
                <listitem>
                    <para>BUILD &ndash; The database instance is being
                        provisioned.</para>
                </listitem>
                <listitem>
                    <para>REBOOT &ndash; The database instance is
                        rebooting.</para>
                </listitem>
                <listitem>
                    <para>ACTIVE &ndash; The database instance is
                        online and available to take requests.</para>
                </listitem>
                <listitem>
                    <para>BLOCKED &ndash; The database instance is
                        unresponsive at the moment.</para>
                </listitem>
                <listitem>
                    <para>RESIZE &ndash; The database instance is
                        being resized at the moment.</para>
                </listitem>
                <listitem>
                    <para>SHUTDOWN &ndash; The database instance is
                        terminating services. Also, SHUTDOWN is
                        returned if for any reason the MySQL instance
                        is shut down but not the actual server.</para>
                    <note>
                        <para>If MySQL has crashed (causing the
                            SHUTDOWN status), please call support for
                            assistance.</para>
                    </note>
                </listitem>
                <listitem>
                    <para>ERROR &ndash; The last operation for the
                        database instance failed due to an
                        error.</para>
                </listitem>
            </itemizedlist>
        </section>
    </chapter>

    <chapter xml:id="API_Operations-d1e2264"
        xmlns="http://docbook.org/ns/docbook" role="api-reference">
        <title>API Operations</title>
        <note>
            <para>Do not use trailing slashes (/) at the end of calls
                to API operations, since this may cause the call to
                fail. For example, do not use &GET; /instances/detail/
                (with the trailing slash at the end). Rather, use
                &GET; /instances/detail instead.</para>
        </note>
        <?hard-pagebreak?>
        <section xml:id="API_Versions">
            <title>API Versions</title>
            <para>This section describes the versions that are
                supported for the Cloud Databases API.</para>
            <wadl:resources
                xmlns:wadl="http://wadl.dev.java.net/2009/02">
                <wadl:resource href="xsd/dbaas.wadl#versions">
                    <wadl:method href="getVersions"/>
                </wadl:resource>
                <wadl:resource href="xsd/dbaas.wadl#version">
                    <wadl:method href="getVersionInfo"/>
                </wadl:resource>
            </wadl:resources>

        </section>

        <section xml:id="Database_Instances">
            <title>Database Instances</title>
            <para>This section describes the operations that are
                supported for database instances.</para>
            <wadl:resources
                xmlns:wadl="http://wadl.dev.java.net/2009/02">
                <wadl:resource href="xsd/dbaas.wadl#instances">
                    <wadl:method href="createInstance"/>
                    <wadl:method href="getInstance"/>
                </wadl:resource>

                <wadl:resource href="xsd/dbaas.wadl#instanceId">
                    <wadl:method href="getInstanceById"/>
                    <wadl:method href="deleteInstance"/>
                </wadl:resource>
                <wadl:resource href="xsd/dbaas.wadl#root">
                    <wadl:method href="createRoot"/>
                    <wadl:method href="isRootEnabled"/>
                </wadl:resource>
            </wadl:resources>
        </section>

        <section xml:id="Database_Instances_Actions">
            <title>Database Instance Actions</title>
            <para>This section describes the actions that are
                supported for database instances.</para>
            <wadl:resources
                xmlns:wadl="http://wadl.dev.java.net/2009/02">
                <wadl:resource href="xsd/dbaas.wadl#instanceAction">
                    <wadl:method href="restartInstance"/>
                    <wadl:method href="resizeInstance"/>
                    <wadl:method href="resizeVolume"/>
                </wadl:resource>
            </wadl:resources>
        </section>

        <section xml:id="databases">
            <title>Databases</title>
            <para>This section describes the operations that are
                supported for databases.</para>
            <wadl:resources
                xmlns:wadl="http://wadl.dev.java.net/2009/02">
                <wadl:resource href="xsd/dbaas.wadl#databases">
                    <wadl:method href="createDatabase"/>
                    <wadl:method href="getDatabases"/>
                </wadl:resource>
                <wadl:resource href="xsd/dbaas.wadl#databaseName">
                    <wadl:method href="deleteDatabase"/>
                </wadl:resource>
            </wadl:resources>
        </section>

        <section xml:id="user_management">
            <title>Users</title>
            <para>This section describes the operations that are
                supported for managing database users.</para>
            <para>In this section, "user has access to a database"
                means that the user has full create, read, update, and
                delete access to the given database. In other words,
                on a cloud database instance, a user named USER and a
                database named DATABASE exist, and within MySQL, a
                GRANT ALL ON DATABASE.* TO USER has been issued on the
                instance.</para>
            <warning>
                <para>There is a bug in a python library that
                    development is using that may cause incorrect user
                    deletions to occur if a period (.) is used in the
                    user name. In this case, the user name is
                    truncated to remove the portion of the name from
                    the period to the end, leaving only the portion
                    from the beginning up to the period. For example,
                    for a user named "my.userA", the bug would
                    truncate the user name to "my", and if the user
                    "my" exists, that user will be incorrectly
                    deleted. To avoid the problem, do not use periods
                    in user names.</para>
            </warning>
            <wadl:resources
                xmlns:wadl="http://wadl.dev.java.net/2009/02">
                <wadl:resource href="xsd/dbaas.wadl#users">
                    <wadl:method href="createUser"/>
                    <wadl:method href="getUsers"/>
                    <wadl:method href="changePass"/>
                </wadl:resource>
                <wadl:resource href="xsd/dbaas.wadl#userId">
                    <wadl:method href="listUser"/>
                    <wadl:method href="deleteUser"/>
                    <wadl:resource href="xsd/dbaas.wadl#database">
                        <wadl:method href="getUserAccess"/>
                        <wadl:method href="grantUserAccess"/>
                        <wadl:resource href="xsd/dbaas.wadl#dbName">
                            <wadl:method href="revokeUserAccess"/>
                        </wadl:resource>
                    </wadl:resource>
                </wadl:resource>
            </wadl:resources>
        </section>

        <section xml:id="flavors">
            <title>Flavors</title>
            <para>This section describes the operations that are
                supported for flavors.</para>
            <wadl:resources
                xmlns:wadl="http://wadl.dev.java.net/2009/02">
                <wadl:resource href="xsd/dbaas.wadl#flavors">
                    <wadl:method href="getFlavors"/>
                </wadl:resource>

                <wadl:resource href="xsd/dbaas.wadl#flavorId">
                    <wadl:method href="getFlavorById"/>
                </wadl:resource>
            </wadl:resources>
        </section>
    </chapter>
    <glossary>
        <title>Glossary</title>
        <glossentry xml:id="Database-d1e017">
            <glossterm>database</glossterm>
            <glossdef>
                <para>A MySQL database within a database
                    instance.</para>
            </glossdef>
        </glossentry>
        <glossentry xml:id="Database-Instance-d1e016">
            <glossterm>database instance</glossterm>
            <glossdef>
                <para>A database instance is an isolated MySQL
                    instance in a single tenant environment on a
                    shared physical host machine. Also referred to as
                    instance.</para>
            </glossdef>
        </glossentry>
        <glossentry xml:id="Flavor-d1e018">
            <glossterm>flavor</glossterm>
            <glossdef>
                <para>A flavor is an available hardware configuration
                    for a database instance. Each flavor has a unique
                    combination of memory capacity and priority for
                    CPU time.</para>
            </glossdef>
        </glossentry>
        <glossentry xml:id="Volume-d1e019">
            <glossterm>volume</glossterm>
            <glossdef>
                <para>A volume is user-specified storage that contains
                    the MySQL data directory. Volumes are
                    automatically provisioned on shared Internet Small
                    Computer System Interface (iSCSI) storage area
                    networks (SAN) that provide for increased
                    performance, scalability, availability and
                    manageability. Applications with high I/O demands
                    are performance optimized and data is protected
                    through both local and network RAID-10.
                    Additionally, network RAID provides synchronous
                    replication of volumes with automatic failover and
                    load balancing across available storage
                    clusters.</para>
            </glossdef>
        </glossentry>
    </glossary>
</book>
