GET'> PUT'> POST'> DELETE'> '> '> ]> Rackspace Cloud Databases Management Developer Guide Rackspace Cloud 2011 2012 Rackspace US, Inc. API v1.0 Rackspace Cloud Databases 2012-10-04 Copyright details are filled in by the template. This document is intended for software developers interested in developing service management applications using the Rackspace Cloud Databases Application Programming Interface (API). 2012-10-04 Added new API call List All Active Accounts (see ). 2012-10-02 Added new API calls Get Hardware Info (see ) and Update All Instances on Host (see ). Added tenant_id field to sample responses for List All Instances for a Host API call (see ). 2012-08-21 Changed FAILED status for database instance to ERROR instead (see ). 2012-08-01 Initial Unlimited Availability (UA) release for Rackspace Cloud Databases. this is a placeholder for the front cover this is a placeholder for the back cover 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 Cloud Databases Developer Guide for Service Management. Writer: need to synch up Overview section with marketing blurb for web. These should be consistent. 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. The following figure shows an overview of Cloud Databases Infrastructure: 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. We welcome feedback, comments, and bug reports at http://feedback.rackspacecloud.com. 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.

Two APIs provide access to Rackspace Cloud Databases: The management 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. The public API, available to developers within Rackspace and Rackspace customers, is the subject of a companion document, the Cloud Databases Developer Guide. To use the information provided here, you should first have a general understanding of the Database service. You should also be familiar with: Database terminology ReSTful web services HTTP/1.1 conventions JSON and/or XML data serialization formats ATOM Syndication Format

This version of the Developer Guide replaces and obsoletes all previous versions. The most recent changes are described in the table below:

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: The WADL is . The XSD is . You can download the most current versions of other API-related documents from http://docs.rackspace.com/. For information about getting started using Cloud Databases and Cloud Servers, refer to Getting Started with Rackspace Cloud Databases and Servers. For more details about Rackspace Cloud Databases, refer to http://www.rackspace.com/cloud/cloud_hosting_products/databases/. This site also offers links to Rackspace's official support channels, including knowledge center articles, forums, phone, chat, and email. Please visit our Product Feedback Forum to find out what customers think about Cloud Databases. You can also follow Rackspace updates and announcements via twitter at http://www.twitter.com/rackspace. This API uses standard HTTP 1.1 response codes as documented at http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html.

To use the Cloud Databases API effectively, you should understand several key concepts: Reviewer: Daniel Morris is asking Daniel Salinas to do an initial write-up of this chapter.

A database instance is an isolated MySQL instance in a single tenant environment on a shared physical host machine. Writer: once we support MSSQL, we need to describe here what is used for MSSQL in place of database instance.

A MySQL database within a database instance. Writer: once we support MSSQL, we need to modify the wording here, such as: The actual database, whether it is in MySQL or MSSQL.

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.

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.

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 APIas well as additional data fields not available to customers.

Every ReST request against the Cloud Databases Management API requires that the caller be authenticated with HTTP Basic Auth. If you cannot access the Cloud Databases Management API, please email the Cloud DB team at clouddb_all@rackspace.com to request access. Access will be granted on an as-needed basis until access to the Management API is integrated with Global Auth.

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. Replace the sample account ID number, 1234, as shown in the URLs in this guide, with your actual account number returned as part of the authentication service response. You will find the actual account number after the final '/' in the publicURL field returned by the authentication response. In the following example, you can see from the publicURL field for cloudServers (publicURL="https://servers.api.rackspacecloud.com/v1.0/322781") that the account number is 322781.

The Cloud Databases API supports both the JSON and XML data serialization formats. The request format is specified using the Content-Type header and is required for calls that have a request body. The response format can be specified in requests either by using the Accept header or by adding an .xml or .json 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 Accept header and a query extension, the query extension takes precedence. Some operations support an Atom representation that can be used to efficiently determine when the state of services has changed. Reviewer: the previous sentence will be hidden for the Private Beta, since it does not appear that Atom will be supported yet. Correct?

Response Formats

Format	Accept Header	Query Extension	Default
JSON	application/json	.json	Yes
XML	application/xml	.xml	No
ATOM	application/atom+xml	.atom	No

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? In the request example below, notice that Content-Type is set to application/json, but application/xml is requested via the Accept header: Missing code sample! Therefore an XML response format is returned: Missing code sample!

Reviewer: please give me the updated info for this section. Need to replace info about callback URL, etc. All successful &GET; requests are synchronous 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. &PUT;, &POST;, and &DELETE; calls are asynchronous, 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: Reviewer: need code example Reviewer: need code example The following table shows the attributes for asynchronous responses:

Attributes for Asynchronous Responses

Attribute	Description
jobId	An identifier for the specific request.
callbackUrl	Resource locator for querying the status of the request.

The status for asynchronous calls is retained for up to 24 hours. If a request body does not pass initial validation or an error condition arises, you may receive an immediate error response from the request. When a request is made to the callback URL provided and the job is still running, another 202 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 200 OK and contain the information for the created database. See XXXX for a specific example. 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 400 BAD REQUEST and contain details regarding the specific validation error. If the response from querying a callback URL is a 404 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 404 NOT FOUND. 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.

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 Accept-Encoding header on the request from the client and indicated by the Content-Encoding header in the server response. Unless the header is explicitly set, encoding defaults to disabled.

Encoding Headers

Header Type	Name	Value
HTTP/1.1 Request	Accept-Encoding	gzip
HTTP/1.1 Response	Content-Encoding	gzip

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. To prevent abuse, HTTP sessions have a timeout of 20 seconds before being closed. The server may close the connection at any time and clients should not rely on this behavior.

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: rate limits and absolute limits. Rate limits are thresholds that are reset after a certain amount of time passes. Absolute limits are fixed.

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/v1.0/instances. 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:

Default Rate Limits

Verb	URI		RegEx		Default
&GET; changes-since	*/instances/*		^/vd+.d+/instances.*		3/minute
&POST;	*/instances/*		^/vd+.d+/instances.*		10/minute
&POST; instances	*/instances/*		^/vd+.d+/instances.*		50/day
&PUT;	*/instances/*		^/vd+.d+/instances.*		10/minute
&DELETE;	*/instances/*		^/vd+.d+/instances.*		100/minute

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. If you exceed the thresholds established for your account, a 413 (Rate Control) HTTP response will be returned with a Retry-After header to notify the client when it can attempt to try again.

Reviewer: Need to update this entire section. Please give me your updates. Refer to the following table for the absolute limits that are set.

Absolute Limits

Name	Description			Limit
Instances	Maximum number of instances allowed for your account			5
Volume Size	Maximum volume size per instance in gigabytes (GB) for your account			25

The Database Service uses an ISO-8601 compliant date format for the display and consumption of date/time values. 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. yyyy-MM-dd'T'HH:mm:ss.SSSZ See the table below for a description of the date/time format codes. May 19th, 2011 at 8:07:08 AM, GMT-5 would have the following format: 2011-05-19T08:07:08-05:00

Explanation of Date/Time Format Codes

Code	Description
yyyy	Four digit year
MM	Two digit month
dd	Two digit day of month
T	Separator for date/time
HH	Two digit hour of day (00-23)
mm	Two digit minutes of hour
ss	Two digit seconds of the minute
SSS	Three digit milliseconds of the second
Z	RFC-822 timezone

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? To reduce load on the service, list operations will return a maximum of 100 items at a time. This is referred to as pagination. 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. Limit is the restriction on the maximum number of items for that type that can be returned. Offset 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. It is important to note that offset must 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 limit and offset respectively, and both apply only to &GET; calls. If unspecified, they default to limit=100 and offset=0. See the examples that follow. Reviewer: Need code example. Pagination applies only to the calls listed in the following table: Reviewer: need to update the table of paginated API calls below: Verb URI Description &GET; /URI/ List all databases manageable by the account specified. &GET; /URI/?name=Name Filter databases. &GET; /URI/ID List details of the specified database. &GET; /URI/ID/xxx List details xxx. &GET; /URI/ID/yyy List details yyy. See the following section for examples of paged List Databases calls.

Reviewer: please review and give me your updates for this section. For any collection in a result, there is a totalEntries 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 previous and/or next, specifying how to get to the previous and/or next set of records. The previous and/or next link elements are displayed only if there are items available in the corresponding link. See the following examples for details. Reviewer: Need code example. Reviewer: Need code example. Reviewer: Need code example. Reviewer: Need code example. In the previous two response examples, note that totalEntries=112 and that a link has been provided to retrieve the next 3 results (limit=3) in the link element identified by the attribute rel="next" (XML) or "rel":"next" (JSON). 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 (offset=3): Reviewer: Need code example. Reviewer: Need code example. Reviewer: Need code example. Reviewer: Need code example. In the previous two response examples, note that totalEntries=112 and two links have been provided to: Retrieve the next 3 results (limit=3) via the link element identified by the attribute rel="next" (XML) or "rel":"next" (JSON) Retrieve the previous 3 results via the link element identified by the attribute rel="previous" (XML) or "rel":"previous" (JSON)

Reviewer: I have hidden this section, since it does not appear that it will be supported for Private Beta. Correct? 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 changes-since parameter to check for changes since a previous request. The changes-since time is specified as Unix time (the number of seconds since January 1, 1970, 00:00:00 UTC, not counting leap seconds). If nothing has changed since the changes-since time, a 304 (Not Modified) response will be returned. If data has changed, only the items changed since the specified time will be returned in the response. Reviewer: does the following sentence apply, and should it be included? For example, performing a &GET; against https://api.servers.rackspacecloud.com/v1.0/224532/servers?changes-since=1244012982 would list all servers that have changed since Wed, 03 Jun 2009 07:09:42 UTC.

Reviewer: need to update this section as needed for Cloud Databases. 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. The following table lists possible fault types with their associated error codes and descriptions. Fault Type Associated Error Code Description badRequest 400 There was one or more errors in the user request. unauthorized 401 The supplied token is not authorized to access the resources, either it's expired or invalid. forbidden 403 Access to the requested resource was denied. itemNotFound 404 The back-end services did not find anything matching the Request-URI. badMethod 405 The request method is not allowed for this resource. overLimit 413 Either the number of entities in the request is larger than allowed limits, or the user has exceeded allowable request rate limits. See the details element for more specifics. Contact support if you think you need higher request rate limits. badMediaType 415 The requested content type is not supported by this service. unprocessableEntity 422 The requested resource could not be processed on at the moment. instanceFault 500 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. notImplemented 501 The requested method or resource is not implemented. serviceUnavailable 503 The Database Service is not available. The following two instanceFault examples show errors when the server has erred or cannot perform the requested operation: The error code (code) is returned in the body of the response for convenience. The message element returns a human-readable message that is appropriate for display to the end user. The details element is optional and may contain information that is useful for tracking down an error, such as a stack trace. The details element may or may not be appropriate for display to an end user, depending on the role and experience of the end user. The fault's root element (for example, instanceFault) may change depending on the type of error. The following two badRequest examples show errors when the volume size is invalid: The next two examples show itemNotFound errors:

When making an API call to create, list, or delete database instance(s), the following database instance status values are possible: BUILD – The database instance is being provisioned. REBOOT – The database instance is rebooting. ACTIVE – The database instance is online and available to take requests. BLOCKED – The database instance is unresponsive at the moment. RESIZE – The database instance is being resized at the moment. 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. 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. ERROR – The last operation for the database instance failed due to an error.

This section describes the operations that are supported for managing database instances.

This section describes the operations that are supported for getting host information.

This section describes the actions that are supported for database instances.

This section describes the operations that are supported for getting information about storage devices.

This section describes the operations that are supported for accounts.