1268 lines
63 KiB
XML
1268 lines
63 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE book [
|
|
<!-- Some useful entities borrowed from HTML -->
|
|
<!ENTITY ndash "–">
|
|
<!ENTITY mdash "—">
|
|
<!ENTITY hellip "…">
|
|
|
|
<!-- 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="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>Rackspace Cloud Databases Developer Guide for Service
|
|
Management</title>
|
|
<?rax status.bar.text="RAX INTERNAL"?>
|
|
<titleabbrev>Rackspace Cloud Databases Management Developer
|
|
Guide</titleabbrev>
|
|
<info>
|
|
<author>
|
|
<personname>
|
|
<firstname/>
|
|
<surname/>
|
|
</personname>
|
|
<affiliation>
|
|
<orgname>Rackspace Cloud</orgname>
|
|
</affiliation>
|
|
</author>
|
|
<copyright>
|
|
<year>2011</year>
|
|
<year>2012</year>
|
|
<holder>Rackspace US, Inc.</holder>
|
|
</copyright>
|
|
<releaseinfo>API v1.0</releaseinfo>
|
|
<productname>Rackspace Cloud Databases</productname>
|
|
<pubdate>2012-10-04</pubdate>
|
|
<legalnotice role="rs-api">
|
|
<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 service management
|
|
applications using the Rackspace Cloud Databases
|
|
Application Programming Interface
|
|
(<abbrev>API</abbrev>). </para>
|
|
</abstract>
|
|
|
|
<revhistory>
|
|
<revision>
|
|
<date>2012-10-04</date>
|
|
<revdescription>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Added new API call List All Active
|
|
Accounts (see <xref
|
|
linkend="GET_getaccounts_mgmt_accounts_"
|
|
/>).</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2012-10-02</date>
|
|
<revdescription>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Added new API calls Get Hardware
|
|
Info (see <xref
|
|
linkend="GET_getHwInfo_mgmt_instances__instanceId__hwinfo_"
|
|
/>) and Update All Instances on Host
|
|
(see <xref
|
|
linkend="POST_updateHostInstances_mgmt_hosts__hostId__instances_action_"
|
|
/>).</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Added tenant_id field to sample
|
|
responses for List All Instances for a
|
|
Host API call (see <xref
|
|
linkend="GET_gethostbyid_mgmt_hosts__hostId__"
|
|
/>).</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2012-08-21</date>
|
|
<revdescription>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Changed FAILED status for database
|
|
instance to ERROR instead (see <xref
|
|
linkend="database_instance_status"
|
|
/>).</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</revdescription>
|
|
</revision>
|
|
<revision>
|
|
<date>2012-08-01</date>
|
|
<revdescription>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Initial Unlimited Availability (UA)
|
|
release for Rackspace Cloud
|
|
Databases.</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>
|
|
</info>
|
|
<chapter xml:id="overview">
|
|
<title>Overview</title>
|
|
<para>Rackspace Cloud Databases is a database available to
|
|
Rackspace Open Cloud customers. Interactions with Cloud
|
|
Databases occur programmatically via the Cloud Databases
|
|
API as described in this <citetitle>Cloud Databases
|
|
Developer Guide for Service
|
|
Management</citetitle>.</para>
|
|
<remark>Writer: need to synch up Overview section with
|
|
marketing blurb for web. These should be
|
|
consistent.</remark>
|
|
<para>The API operations described in this manual relate to
|
|
support of Cloud Databases service activities on behalf of
|
|
a specific customer. The scope of these operations is
|
|
narrow, relating to the needs of a single customer. A
|
|
customer might directly request these operations, however
|
|
only Rackers are authorized to perform them.</para>
|
|
<para>The following figure shows an
|
|
overview of Cloud Databases Infrastructure: <informalfigure>
|
|
<mediaobject>
|
|
<imageobject role="fo">
|
|
<imagedata
|
|
fileref="images/Cloud_DB_Infographic-1.svg"
|
|
contentwidth="6in"/>
|
|
</imageobject>
|
|
<imageobject role="html">
|
|
<imagedata
|
|
fileref="images/Cloud_DB_Infographic-1.png"
|
|
/>
|
|
</imageobject>
|
|
</mediaobject>
|
|
</informalfigure>
|
|
</para>
|
|
<remark>Writer: need to get architecture diagram for DBaaS.
|
|
Daniel emailed 11/17 that he would work on this during the
|
|
Private Beta and have it done for the Public
|
|
Beta.</remark>
|
|
<para security="writeronly">We welcome feedback, comments, and bug reports at <link
|
|
xlink:href="http://feedback.rackspacecloud.com"
|
|
>http://feedback.rackspacecloud.com</link>.</para>
|
|
<remark>Writer: check whether following statement should be
|
|
added back in for public (not private) beta: Issues and
|
|
bug reports can be directed to your support team via
|
|
ticket, chat, email, or phone.</remark>
|
|
<section xml:id="Intended_Audience-d1e122">
|
|
<title>Intended Audience</title>
|
|
<para>Two APIs provide access to Rackspace Cloud
|
|
Databases: </para>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>The <emphasis>management</emphasis> API,
|
|
available only to developers, Support
|
|
personnel, and Operations administrators
|
|
within Rackspace, depending on the granted
|
|
LDAP roles/permissions, is the subject of this
|
|
document.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>The <emphasis>public</emphasis> API,
|
|
available to developers within Rackspace and
|
|
Rackspace customers, is the subject of a
|
|
companion document, the <citetitle>Cloud
|
|
Databases Developer
|
|
Guide</citetitle>.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>To use the information provided here, you should
|
|
first have a general understanding of the Database
|
|
service. You should also be familiar with: </para>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>Database terminology</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>ReSTful web services</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>HTTP/1.1 conventions</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>JSON and/or XML data serialization
|
|
formats</para>
|
|
</listitem>
|
|
<listitem security="writeronly">
|
|
<para>ATOM Syndication 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>Descriptive information about Cloud Databases is
|
|
also published in its Web Application Description
|
|
Language (WADL) and XML Schema Definition (XSD). You
|
|
are welcome to read this information here:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>The WADL is <link
|
|
xlink:href="http://docs-internal.rackspace.com/cdb/api/v1.0/management.wadl"
|
|
/>.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>The XSD is <link
|
|
xlink:href="http://docs-internal.rackspace.com/cdb/api/v1.0/xsd/management.xsd"/>. </para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>You can download the most current versions of other
|
|
API-related documents from <link
|
|
xlink:href="http://docs.rackspace.com/"
|
|
>http://docs.rackspace.com/</link>. </para>
|
|
<para>For information about getting started using Cloud
|
|
Databases and Cloud Servers, refer to
|
|
<citetitle>Getting Started with Rackspace Cloud
|
|
Databases and Servers</citetitle>.</para>
|
|
<para>For more details about Rackspace Cloud Databases,
|
|
refer to <link
|
|
xlink:href="http://www.rackspace.com/cloud/cloud_hosting_products/databases/"
|
|
>http://www.rackspace.com/cloud/cloud_hosting_products/databases/</link>.
|
|
This site also offers links to Rackspace's official
|
|
support channels, including knowledge center articles,
|
|
forums, phone, chat, and email. </para>
|
|
<para>Please visit our <link
|
|
xlink:href="http://feedback.rackspacecloud.com/forums/71021-product-feedback/category/42449-cloud-databases"
|
|
>Product Feedback Forum</link> to find out what
|
|
customers think about Cloud Databases.</para>
|
|
<para>You can also follow Rackspace updates and
|
|
announcements via twitter at <link
|
|
xlink:href="http://www.twitter.com/rackspace"
|
|
>http://www.twitter.com/rackspace</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>
|
|
</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>
|
|
<remark>Reviewer: Daniel Morris is asking Daniel Salinas to
|
|
do an initial write-up of this chapter.</remark>
|
|
<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 dedicated 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 Management API is implemented using
|
|
a ReSTful web service interface. Most functions of the
|
|
customer-facing Cloud Databases API may be accessed on
|
|
behalf of a customer. The Cloud Databases Management API
|
|
also extends this functionality to include operations for
|
|
managing features of the public API<remark>as well as
|
|
additional data fields not available to
|
|
customers</remark>.</para>
|
|
<section xml:id="Authentication-d1e647">
|
|
<title>Authentication</title>
|
|
<para>Every ReST request against the Cloud Databases
|
|
Management API requires that the caller be
|
|
authenticated with HTTP Basic Auth.</para>
|
|
<note>
|
|
<para>If you cannot access the Cloud Databases
|
|
Management API, please email the Cloud DB team at
|
|
<email>clouddb_all@rackspace.com</email> to
|
|
request access. Access will be granted on an
|
|
as-needed basis until access to the Management API
|
|
is integrated with Global Auth.</para>
|
|
</note>
|
|
</section>
|
|
<section xml:id="Service_Access_Endpoints-d1e753">
|
|
<title>Service Access</title>
|
|
<para>The Database Service is a regionalized service. The
|
|
user of the service is therefore responsible for
|
|
appropriate replication, caching, and overall
|
|
maintenance of Cloud Databases data across regional
|
|
boundaries to other Cloud Databases servers.</para>
|
|
<?rax-fo keep-with-next?>
|
|
<para>Replace the sample account ID number,
|
|
<parameter>1234</parameter>, as shown in the URLs
|
|
in this guide, with your actual account number
|
|
returned as part of the authentication service
|
|
response.</para>
|
|
<para>You will find the actual account number after the
|
|
final '/' in the <code>publicURL</code> field returned
|
|
by the authentication response. In the following
|
|
example, you can see from the <code>publicURL</code>
|
|
field for <code>cloudServers</code>
|
|
(publicURL="https://servers.api.rackspacecloud.com/v1.0/322781")
|
|
that the account number is 322781.</para>
|
|
</section>
|
|
<section xml:id="Request_Response_Types-d1e503">
|
|
<title>Request/Response Types</title>
|
|
<para> The Cloud Databases API supports both the JSON and
|
|
XML data serialization formats. The request format is
|
|
specified using the <code>Content-Type</code> header
|
|
and is <emphasis>required</emphasis> for calls that
|
|
have a request body. The response format can be
|
|
specified in requests either by using the
|
|
<code>Accept</code> header or by adding an
|
|
<code>.xml</code> or <code>.json</code> extension
|
|
to the request URI. Note that it is possible for a
|
|
response to be serialized using a format different
|
|
from the request. If no response format is specified,
|
|
JSON is the default. If conflicting formats are
|
|
specified using both an <code>Accept</code> header and
|
|
a query extension, the query extension takes
|
|
precedence.</para>
|
|
<para security="writeronly">Some operations support an Atom representation that
|
|
can be used to efficiently determine when the state of
|
|
services has changed. </para>
|
|
<remark>Reviewer: the previous sentence will be hidden
|
|
for the Private Beta, since it does not appear that
|
|
Atom will be supported yet. Correct?</remark>
|
|
<table rules="all">
|
|
<caption>Response Formats</caption>
|
|
<?dbfo keep-together="always"?>
|
|
<thead>
|
|
<tr align="center">
|
|
<td>Format</td>
|
|
<td>Accept Header</td>
|
|
<td>Query Extension</td>
|
|
<td>Default</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>JSON</td>
|
|
<td>application/json</td>
|
|
<td>.json</td>
|
|
<td>Yes</td>
|
|
</tr>
|
|
<tr>
|
|
<td>XML</td>
|
|
<td>application/xml</td>
|
|
<td>.xml</td>
|
|
<td>No</td>
|
|
</tr>
|
|
<tr security="writeronly">
|
|
<td>ATOM</td>
|
|
<td>application/atom+xml</td>
|
|
<td>.atom</td>
|
|
<td>No</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<remark>Reviewer: the ATOM row in the table above will be
|
|
hidden for the Private Beta, since it does not appear
|
|
that Atom will be supported yet. Correct?</remark>
|
|
<para>In the request example below, notice that
|
|
<parameter>Content-Type</parameter> is set to
|
|
<parameter>application/json</parameter>, but
|
|
<parameter>application/xml</parameter> is
|
|
requested via the <parameter>Accept</parameter>
|
|
header:</para>
|
|
<example xml:id="request_with_headers_json">
|
|
<title>Request with Headers: JSON</title>
|
|
<?dbfo keep-together="always"?>
|
|
<programlisting language="json"><xi:include href="samples/db-request-types.json" parse="text"><xi:fallback>Missing code sample!<?rax fail?></xi:fallback></xi:include></programlisting>
|
|
</example>
|
|
<para><?rax-fo keep-with-next?>Therefore an XML response format is returned:</para>
|
|
<example>
|
|
<title>Response with Headers: XML</title>
|
|
<?dbfo keep-together="always"?>
|
|
<programlisting language="xml"><xi:include href="samples/db-response-types.xml" parse="text"><xi:fallback>Missing code sample!<?rax fail?></xi:fallback></xi:include></programlisting>
|
|
</example>
|
|
</section>
|
|
<section xml:id="sync_asynch_responses" security="writeronly">
|
|
<title>Synchronous and Asynchronous Responses</title>
|
|
<remark>Reviewer: please give me the updated info for this
|
|
section. Need to replace info about callback URL,
|
|
etc.</remark>
|
|
<para> All successful &GET; requests are
|
|
<emphasis>synchronous</emphasis> calls, since they
|
|
are always retrieving (reading) existing information.
|
|
With these requests, the caller waits until the call
|
|
returns with the specified code and response body. For
|
|
an example, see XXXX.</para>
|
|
<para>&PUT;, &POST;, and &DELETE; calls are <emphasis>asynchronous</emphasis>, however,
|
|
since they may take some time to process. Therefore they return 202 ACCEPTED
|
|
responses containing information with a callback URL, which allows the progress,
|
|
status, and/or response information of the call to be retrieved at a later point in
|
|
time. The asynchronous response body will look similar to the following examples,
|
|
depending on the format requested:</para>
|
|
<example>
|
|
<title>202 ACCEPTED Response: XML</title>
|
|
<?dbfo keep-together="always"?>
|
|
<programlisting language="xml">Reviewer: need code example</programlisting>
|
|
</example>
|
|
<example>
|
|
<title>202 ACCEPTED Response: JSON</title>
|
|
<?dbfo keep-together="always"?>
|
|
<programlisting language="json">Reviewer: need code example</programlisting>
|
|
</example>
|
|
<para>The following table shows the attributes for asynchronous responses:</para>
|
|
<table rules="all">
|
|
<caption>Attributes for Asynchronous Responses</caption>
|
|
<?dbfo keep-together="always"?>
|
|
<thead>
|
|
<tr align="center">
|
|
<td colspan="1">Attribute</td>
|
|
<td colspan="4">Description</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td colspan="1">jobId</td>
|
|
<td colspan="4">An identifier for the specific request.</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">callbackUrl</td>
|
|
<td colspan="4">Resource locator for querying the status of the request.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<note>
|
|
<para>The status for asynchronous calls is retained for up to 24 hours.</para>
|
|
</note>
|
|
<note>
|
|
<para>If a request body does not pass initial validation or an error condition
|
|
arises, you may receive an immediate error response from the request.</para>
|
|
</note>
|
|
<para>When a request is made to the callback URL provided
|
|
and the job is still running, another
|
|
<returnvalue>202</returnvalue> ACCEPTED response
|
|
is returned with the same information as the previous
|
|
one. If the request is complete, the response will be
|
|
as if the original call returned as normal, without
|
|
waiting. For example, if a Create Database request was
|
|
issued and a 202 asynchronous response was returned,
|
|
the response from querying the callback URL for a
|
|
completed successful database creation would be a
|
|
<returnvalue>200</returnvalue> OK and contain the
|
|
information for the created database. See XXXX for a
|
|
specific example.</para>
|
|
<para>If an error occurs during the processing of the
|
|
create request, querying the callback URL will return
|
|
the details of the error, as if the original call
|
|
returned the error response. For example, if a
|
|
validation error occurs during the Create Database
|
|
request above, the response from querying the callback
|
|
URL would be a <returnvalue>400</returnvalue> BAD
|
|
REQUEST and contain details regarding the specific
|
|
validation error.</para>
|
|
<note>
|
|
<para>If the response from querying a callback URL is a
|
|
<returnvalue>404</returnvalue> NOT FOUND, the details of the error in the
|
|
response body will contain information the caller may use to determine whether
|
|
the specified job itself was not found, or if the response from the original
|
|
request was a <returnvalue>404</returnvalue> NOT FOUND. </para>
|
|
</note>
|
|
<para>The description of each &PUT;, &POST;, and &DELETE;
|
|
request identifies the response codes that can
|
|
indicate success or error for that request. For
|
|
example, see XXXX immediately below the table for a
|
|
list of the successful and error response codes for
|
|
the POST /xxxx call.</para>
|
|
</section>
|
|
<section xml:id="Content_Compression-d1e1120" security="writeronly">
|
|
<title>Content Compression</title>
|
|
<para> Request and response body data may be encoded with gzip compression to accelerate
|
|
interactive performance of API calls and responses. This is controlled using the
|
|
<code>Accept-Encoding</code> header on the request from the client and indicated
|
|
by the <code>Content-Encoding</code> header in the server response. Unless the
|
|
header is explicitly set, encoding defaults to disabled. </para>
|
|
<table rules="all">
|
|
<caption>Encoding Headers</caption>
|
|
<?dbfo keep-together="always"?>
|
|
<thead>
|
|
<tr align="center">
|
|
<td>Header Type</td>
|
|
<td>Name</td>
|
|
<td>Value</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>HTTP/1.1 Request</td>
|
|
<td><code>Accept-Encoding</code></td>
|
|
<td>gzip</td>
|
|
</tr>
|
|
<tr>
|
|
<td>HTTP/1.1 Response</td>
|
|
<td><code>Content-Encoding</code></td>
|
|
<td>gzip</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
<section xml:id="Persistent_Connections-d1e1187" security="writeronly">
|
|
<title>Persistent Connections</title>
|
|
<para>
|
|
By default, the API supports persistent connections
|
|
via HTTP/1.1 keepalives. All connections will be kept
|
|
alive unless the connection header is set to close.
|
|
</para>
|
|
<para>
|
|
To prevent abuse, HTTP sessions have a timeout of 20
|
|
seconds before being closed.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
The server may close the connection at any time
|
|
and clients should not rely on this behavior.
|
|
</para>
|
|
</note>
|
|
</section>
|
|
<?hard-pagebreak?>
|
|
<section xml:id="Limits-d1e1208">
|
|
<title>Limits</title>
|
|
<para>
|
|
All accounts, by default, have a preconfigured set of
|
|
thresholds (or limits) to manage capacity and prevent
|
|
abuse of the system. The system recognizes two kinds
|
|
of limits: <firstterm>rate limits</firstterm> and
|
|
<firstterm>absolute limits</firstterm>. Rate limits
|
|
are thresholds that are reset after a certain amount
|
|
of time passes. Absolute limits are fixed.
|
|
</para>
|
|
<section xml:id="Rate_Limits-d1e1222">
|
|
<title>Rate Limits</title>
|
|
<para> Rate limits are specified in terms of both a
|
|
human-readable wild-card URI and a
|
|
machine-processable regular expression. The
|
|
regular expression boundary matcher '^' takes
|
|
effect after the root URI path. For example, the
|
|
regular expression ^/v1.0/instances would match
|
|
the bolded portion of the following URI:
|
|
https://ord.databases.api.rackspacecloud.com<emphasis
|
|
role="bold">/v1.0/instances</emphasis>. </para>
|
|
<para>The following table specifies the default rate
|
|
limits for all API operations for all &GET;,
|
|
&POST;, &PUT;, and &DELETE; calls for databases
|
|
and database instances: </para>
|
|
<table rules="all">
|
|
<caption>Default Rate Limits</caption>
|
|
<thead>
|
|
<tr align="center">
|
|
<td colspan="1">Verb</td>
|
|
<td colspan="2">URI</td>
|
|
<td colspan="2">RegEx</td>
|
|
<td colspan="1">Default</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td colspan="1">&GET; changes-since</td>
|
|
<td colspan="2">*/instances/*</td>
|
|
<td colspan="2">^/vd+.d+/instances.*</td>
|
|
<td colspan="1">3/minute</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">&POST;</td>
|
|
<td colspan="2">*/instances/*</td>
|
|
<td colspan="2">^/vd+.d+/instances.*</td>
|
|
<td colspan="1">10/minute</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">&POST; instances</td>
|
|
<td colspan="2">*/instances/*</td>
|
|
<td colspan="2">^/vd+.d+/instances.*</td>
|
|
<td colspan="1">50/day</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">&PUT;</td>
|
|
<td colspan="2">*/instances/*</td>
|
|
<td colspan="2">^/vd+.d+/instances.*</td>
|
|
<td colspan="1">10/minute</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">&DELETE;</td>
|
|
<td colspan="2">*/instances/*</td>
|
|
<td colspan="2">^/vd+.d+/instances.*</td>
|
|
<td colspan="1">100/minute</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<para> Rate limits are applied in order relative to the
|
|
verb, going from least to most specific. For
|
|
example, although the threshold for &POST; to
|
|
/v1.0/* is 10 per minute, one cannot &POST; to
|
|
/v1.0/* more than 50 times within a single day. </para>
|
|
<para> If you exceed the thresholds established for
|
|
your account, a <errorcode>413 (Rate
|
|
Control)</errorcode> HTTP response will be
|
|
returned with a <code>Retry-After</code> header to
|
|
notify the client when it can attempt to try
|
|
again. </para>
|
|
</section>
|
|
<section xml:id="Absolute_Limits-d1e1397">
|
|
<title>Absolute Limits</title>
|
|
<remark>Reviewer: Need to update this entire section.
|
|
Please give me your updates.</remark>
|
|
<para>Refer to the following table for the absolute
|
|
limits that are set.</para>
|
|
<table rules="all">
|
|
<caption>Absolute Limits</caption>
|
|
<thead>
|
|
<tr>
|
|
<td colspan="1">Name</td>
|
|
<td colspan="3">Description</td>
|
|
<td colspan="1">Limit</td>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td colspan="1">Instances</td>
|
|
<td colspan="3">Maximum number of instances allowed
|
|
for your account</td>
|
|
<td colspan="1">5</td>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="1">Volume Size</td>
|
|
<td colspan="3">Maximum volume size per
|
|
instance in gigabytes (GB) for your
|
|
account</td>
|
|
<td colspan="1">25</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</section>
|
|
</section>
|
|
<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" security="writeronly">
|
|
<title>Pagination</title>
|
|
<remark>Reviewer: please review and give me your updates
|
|
for this section. Dev needs to determine which API
|
|
calls support pagination and then supply examples. I
|
|
have hidden this entire section for now, since we do
|
|
not believe that it will be supported for Private
|
|
Beta. Correct?</remark>
|
|
<para>To reduce load on the service, list operations will
|
|
return a maximum of 100 items at a time. This is
|
|
referred to as <emphasis>pagination</emphasis>.</para>
|
|
<para> Pagination is 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 offset. <emphasis>Limit</emphasis> is the restriction on the maximum
|
|
number of items for that type that can be returned. <emphasis>Offset</emphasis> is
|
|
the starting point for the return data. For example, an offset of 50 specifies that
|
|
the items that are returned should start with item number 51 (since the numbering is
|
|
one-based) in the collection. </para>
|
|
<para>It is important to note that offset <emphasis>must</emphasis> be a multiple of the
|
|
limit (or zero), otherwise a Bad Request Exception will be thrown. Both limit and
|
|
offset are specified via request parameters on the URI. The parameters are named
|
|
<code>limit</code> and <code>offset</code> respectively, and both apply only to
|
|
&GET; calls. If unspecified, they default to <code>limit=100</code> and
|
|
<code>offset=0</code>. See the examples that follow.</para>
|
|
<example>
|
|
<title>Examples of Limits and Offsets for Paging Calls</title>
|
|
<?dbfo keep-together="always"?>
|
|
<programlisting language="xml">Reviewer: Need code example.</programlisting>
|
|
</example>
|
|
<para>Pagination applies only to the calls listed in the following table: </para>
|
|
<remark>Reviewer: need to update the table of paginated API
|
|
calls below:</remark>
|
|
<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">/URI/</td>
|
|
<td colspan="3">List all databases manageable
|
|
by the account specified. </td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td colspan="1">&GET;</td>
|
|
<td colspan="2"
|
|
>/URI/?name=<replaceable>Name</replaceable></td>
|
|
<td colspan="3">Filter databases.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td colspan="1">&GET;</td>
|
|
<td colspan="2"
|
|
>/URI/<replaceable>ID</replaceable></td>
|
|
<td colspan="3">List details of the specified
|
|
database.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td colspan="1">&GET;</td>
|
|
<td colspan="2"
|
|
>/URI/<replaceable>ID</replaceable>/xxx</td>
|
|
<td colspan="3">List details xxx.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td colspan="1">&GET;</td>
|
|
<td colspan="2"
|
|
>/URI/<replaceable>ID</replaceable>/yyy</td>
|
|
<td colspan="3">List details yyy.</td>
|
|
</tr>
|
|
|
|
|
|
|
|
</tbody>
|
|
</informaltable>
|
|
<para>See the following section for examples of paged List
|
|
Databases calls.</para>
|
|
<section xml:id="Pagination_Elements_and_Attributes-d1e1754">
|
|
<title>Pagination Elements and Attributes</title>
|
|
<remark>Reviewer: please review and give me your
|
|
updates for this section.</remark>
|
|
<para>For any collection in a result, there is a <code>totalEntries</code> attribute
|
|
representing the total number of entries there are for this item type. If the
|
|
number of items requested in the &GET; call is less then the total number of
|
|
items for this type, then there will be pagination links <code>previous</code>
|
|
and/or <code>next</code>, specifying how to get to the previous and/or next set
|
|
of records. </para>
|
|
<note>
|
|
<para>The <code>previous</code> and/or <code>next</code> link elements are
|
|
displayed only if there are items available in the corresponding link. See
|
|
the following examples for details.</para>
|
|
</note>
|
|
<example>
|
|
<title>List Databases Request with limit:
|
|
XML</title>
|
|
<?dbfo keep-together="always"?>
|
|
<programlisting language="xml">Reviewer: Need code example.</programlisting>
|
|
</example>
|
|
<example>
|
|
<title>List Databases Request with limit:
|
|
JSON</title>
|
|
<?dbfo keep-together="always"?>
|
|
<programlisting language="xml">Reviewer: Need code example.</programlisting>
|
|
</example>
|
|
<example>
|
|
<title>List Databases Response with totalEntries:
|
|
XML</title>
|
|
<?dbfo keep-together="always"?>
|
|
<programlisting language="xml">Reviewer: Need code example.</programlisting>
|
|
</example>
|
|
<example>
|
|
<title>List Databases Response with totalEntries:
|
|
JSON</title>
|
|
<?dbfo keep-together="always"?>
|
|
<programlisting language="xml">Reviewer: Need code example.</programlisting>
|
|
</example>
|
|
<para> In the previous two response examples, note that
|
|
<code>totalEntries=112</code> and that a link has been provided to retrieve
|
|
the next 3 results (<code>limit=3</code>) in the link element identified by the
|
|
attribute <code>rel="next"</code> (XML) or <code>"rel":"next"</code> (JSON). </para>
|
|
<para>The following example shows links to both previous and next results in the
|
|
responses, since the request specified to start with the fourth item in the
|
|
collection (<code>offset=3</code>):</para>
|
|
<example>
|
|
<title>List Databases Request with limit and
|
|
offset: XML</title>
|
|
<?dbfo keep-together="always"?>
|
|
<programlisting language="xml">Reviewer: Need code example.</programlisting>
|
|
</example>
|
|
<example>
|
|
<title>List Databases Request with limit and
|
|
offset: JSON</title>
|
|
<?dbfo keep-together="always"?>
|
|
<programlisting language="xml">Reviewer: Need code example.</programlisting>
|
|
</example>
|
|
<example>
|
|
<title>List Databases Response with Links to
|
|
previous and next Results: XML</title>
|
|
<?dbfo keep-together="always"?>
|
|
<programlisting language="xml">Reviewer: Need code example.</programlisting>
|
|
</example>
|
|
<example>
|
|
<title>List Databases Response with Links to
|
|
previous and next Results: JSON</title>
|
|
<?dbfo keep-together="always"?>
|
|
<programlisting language="xml">Reviewer: Need code example.</programlisting>
|
|
</example>
|
|
<para>
|
|
<?rax-fo keep-with-next?> In the previous two response examples, note that
|
|
<code>totalEntries=112</code> and two links have been provided to:<itemizedlist>
|
|
<listitem>
|
|
<para>Retrieve the next 3 results (<code>limit=3</code>) via the link
|
|
element identified by the attribute <code>rel="next"</code> (XML) or
|
|
<code>"rel":"next"</code> (JSON)</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Retrieve the previous 3 results via the link element identified by
|
|
the attribute <code>rel="previous"</code> (XML) or
|
|
<code>"rel":"previous"</code> (JSON) </para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
</section>
|
|
</section>
|
|
<section xml:id="efficient_polling_changes_since_parm" security="writeronly">
|
|
<title>Efficient Polling with the
|
|
<parameter>Changes-Since</parameter>
|
|
Parameter</title>
|
|
<remark>Reviewer: I have hidden this section, since it
|
|
does not appear that it will be supported for Private
|
|
Beta. Correct?</remark>
|
|
<para> The ReST API allows you to poll for the status of
|
|
certain operations by performing a &GET; on various
|
|
URIs. Rather than re-downloading and re-parsing the
|
|
full status at each polling interval, your ReST client
|
|
may use the <parameter>changes-since</parameter>
|
|
parameter to check for changes since a previous
|
|
request. The <parameter>changes-since</parameter> time
|
|
is specified as <link
|
|
xlink:href="http://en.wikipedia.org/wiki/Unix_time"
|
|
>Unix time</link> (the number of seconds since
|
|
January 1, 1970, 00:00:00 UTC, not counting leap
|
|
seconds). If nothing has changed since the
|
|
<parameter>changes-since</parameter> time, a
|
|
<returnvalue>304 (Not Modified)</returnvalue>
|
|
response will be returned. If data has changed, only
|
|
the items changed since the specified time will be
|
|
returned in the response. </para>
|
|
<remark>Reviewer: does the following sentence apply, and
|
|
should it be included?</remark>
|
|
<para>For example, performing a &GET; against
|
|
https://api.servers.rackspacecloud.com/v1.0/224532/servers?<parameter>changes-since</parameter>=1244012982
|
|
would list all servers that have changed since Wed, 03
|
|
Jun 2009 07:09:42 UTC. </para>
|
|
</section>
|
|
<section xml:id="DB_faults">
|
|
<title>Faults</title>
|
|
<remark>Reviewer: need to update this section as needed
|
|
for Cloud Databases.</remark>
|
|
<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 instanceFault Response: XML</title>
|
|
<?dbfo keep-together="always"?>
|
|
<programlisting language="xml">
|
|
<xi:include href="samples/db-faults-instanceFault.xml" parse="text"/>
|
|
</programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Example instanceFault Response: JSON</title>
|
|
<?dbfo keep-together="always"?>
|
|
<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:
|
|
XML</title>
|
|
<?dbfo keep-together="always"?>
|
|
<programlisting language="xml">
|
|
<xi:include href="samples/db-faults-badRequest.xml" parse="text"/>
|
|
</programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Example badRequest Fault on Volume Size Errors:
|
|
JSON</title>
|
|
<?dbfo keep-together="always"?>
|
|
<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: XML</title>
|
|
<?dbfo keep-together="always"?>
|
|
<programlisting language="xml">
|
|
<xi:include href="samples/db-faults-itemNotFound.xml" parse="text"/>
|
|
</programlisting>
|
|
</example>
|
|
<example>
|
|
<title>Example itemNotFound Fault: JSON</title>
|
|
<?dbfo keep-together="always"?>
|
|
<programlisting language="json">
|
|
<xi:include href="samples/db-faults-itemNotFound.json" parse="text"/>
|
|
</programlisting>
|
|
</example>
|
|
</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 – The database instance is being provisioned.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>REBOOT – The database instance is
|
|
rebooting.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>ACTIVE – The database instance is
|
|
online and available to take requests.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>BLOCKED – The database instance is
|
|
unresponsive at the moment.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>RESIZE – The database instance is being
|
|
resized at the moment.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>SHUTDOWN – 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>
|
|
<para>
|
|
<note>
|
|
<para>If MySQL has crashed (causing the
|
|
SHUTDOWN status), you can try
|
|
rebooting the database instance to see
|
|
if that corrects the problem. If the
|
|
instance still does not recover, you
|
|
can escalate the issue to
|
|
NebOps.</para>
|
|
</note>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>ERROR – 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>
|
|
|
|
<section xml:id="Database_Instance_Management">
|
|
<title>Database Instance Management</title>
|
|
<para>This section describes the operations that are supported for managing database instances.</para>
|
|
<wadl:resources
|
|
xmlns:wadl="http://wadl.dev.java.net/2009/02">
|
|
<wadl:resource href="../../../xsd/management.wadl#instances">
|
|
<wadl:method href="getIndex"/>
|
|
</wadl:resource>
|
|
<wadl:resource href="../../../xsd/management.wadl#instanceId">
|
|
<wadl:method href="showinstances"/>
|
|
</wadl:resource>
|
|
<wadl:resource href="../../../xsd/management.wadl#diagnostics">
|
|
<wadl:method href="getdiagnosticdetails"/>
|
|
</wadl:resource>
|
|
<wadl:resource
|
|
href="../../../xsd/management.wadl#rootdetails">
|
|
<wadl:method href="getrootdetails"/>
|
|
</wadl:resource>
|
|
<wadl:resource
|
|
href="../../../xsd/management.wadl#hwInfo">
|
|
<wadl:method href="getHwInfo"/>
|
|
</wadl:resource>
|
|
</wadl:resources>
|
|
</section>
|
|
|
|
<section xml:id="Host_Information">
|
|
<title>Host Information</title>
|
|
<para>This section describes the operations that are supported for getting host information.</para>
|
|
<wadl:resources
|
|
xmlns:wadl="http://wadl.dev.java.net/2009/02">
|
|
<wadl:resource href="../../../xsd/management.wadl#hosts">
|
|
<wadl:method href="gethosts"/>
|
|
</wadl:resource>
|
|
<wadl:resource href="../../../xsd/management.wadl#hostid">
|
|
<wadl:method href="gethostbyid"/>
|
|
</wadl:resource>
|
|
<wadl:resource href="../../../xsd/management.wadl#instanceAction-hostId">
|
|
<wadl:method href="updateHostInstances"/>
|
|
</wadl:resource>
|
|
</wadl:resources>
|
|
</section>
|
|
|
|
<section xml:id="Management_Instances_Actions">
|
|
<title>Management 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/management.wadl#instanceAction" >
|
|
<wadl:method href="rebootInstance"/>
|
|
|
|
</wadl:resource>
|
|
</wadl:resources>
|
|
</section>
|
|
|
|
<section xml:id="Storage_Management">
|
|
<title>Storage Management</title>
|
|
<para>This section describes the operations that are supported for getting information about storage devices.</para>
|
|
<wadl:resources
|
|
xmlns:wadl="http://wadl.dev.java.net/2009/02">
|
|
<wadl:resource href="../../../xsd/management.wadl#storage">
|
|
<wadl:method href="indexstorage"/>
|
|
</wadl:resource>
|
|
</wadl:resources>
|
|
</section>
|
|
|
|
<section xml:id="Account_Information">
|
|
<title>Account Information</title>
|
|
<para>This section describes the operations that are
|
|
supported for accounts.</para>
|
|
<wadl:resources
|
|
xmlns:wadl="http://wadl.dev.java.net/2009/02">
|
|
<wadl:resource
|
|
href="../../../xsd/management.wadl#accounts">
|
|
<wadl:method href="getaccounts"/>
|
|
</wadl:resource>
|
|
<wadl:resource href="../../../xsd/management.wadl#accountid">
|
|
<wadl:method href="getaccountbyid"/>
|
|
</wadl:resource>
|
|
</wadl:resources>
|
|
</section>
|
|
|
|
</chapter>
|
|
</book>
|