# Rackspace Cloud Databases Developer Guide for Service Management

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

## Overview

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.

### Intended Audience

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

### Document Change History

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

### Additional Resources

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.

## Concepts

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.

### Database Instance

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.

### Database

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.

### Flavor

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.

### Volume

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.

## General API Information

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.

### Authentication

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.

### Service Access

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.

### Request/Response Types

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:

Request with Headers: JSON

    Missing code sample!

Therefore an XML response format is returned:

Response with Headers: XML

    Missing code sample!

### Synchronous and Asynchronous Responses

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:

202 ACCEPTED Response: XML

    Reviewer: need code example

202 ACCEPTED Response: JSON

    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.

### Content Compression

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

### Persistent Connections

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.

### Limits

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

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.

#### Absolute Limits

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

### Date/Time Format

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.

DB Service Date/Time Format

    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

### Pagination

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.

Examples of Limits and Offsets for Paging Calls

    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.

#### Pagination Elements and Attributes

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.

List Databases Request with limit: XML

    Reviewer: Need code example.

List Databases Request with limit: JSON

    Reviewer: Need code example.

List Databases Response with totalEntries: XML

    Reviewer: Need code example.

List Databases Response with totalEntries: JSON

    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`):

List Databases Request with limit and offset: XML

    Reviewer: Need code example.

List Databases Request with limit and offset: JSON

    Reviewer: Need code example.

List Databases Response with Links to previous and next Results: XML

    Reviewer: Need code example.

List Databases Response with Links to previous and next Results: JSON

    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)

### Efficient Polling with the Changes-Since Parameter

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.

### Faults

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:

Example instanceFault Response: XML

Example instanceFault Response: JSON

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:

Example badRequest Fault on Volume Size Errors: XML

Example badRequest Fault on Volume Size Errors: JSON

The next two examples show `itemNotFound` errors:

Example itemNotFound Fault: XML

Example itemNotFound Fault: JSON

### Database Instance Status

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.

## API Operations

### Database Instance Management

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

### Host Information

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

### Management Instance Actions

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

### Storage Management

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

### Account Information

This section describes the operations that are supported for accounts.