GET'> PUT'> POST'> DELETE'> '> '> ]> Rackspace Cloud Databases Developer Guide Rackspace Cloud 2010 2011 2012 Rackspace US, Inc. API v1.0 Rackspace Cloud Databases 2012-09-04 Copyright details are filled in by the template. This document is intended for software developers interested in developing applications using the Rackspace Cloud Databases Application Programming Interface (API). 2012-09-04 Added information for pricing and service level (refer to ). Updated maximum volume size for a database instance (refer to ). 2012-08-21 Changed FAILED status for database instance to ERROR instead (see ). List reserved names that cannot be used for creating databases (see ) and users (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 cdb 2 Rackspace Cloud Databases is an OpenStack-based MySQL relational database service that allows Rackspace customers to easily provision database instances of varying virtual resource sizes without the need to maintain and/or update MySQL. Interactions with Cloud Databases occur programmatically via the Cloud Databases API as described in this developer guide. Rackspace recommends that Cloud Databases users back up their data using mysqldump until backups are supported in Cloud Databases. The following figure shows an overview of Cloud Databases Infrastructure: Writer: need to get architecture diagram for DBaaS. Emailed Daniel 5/1/12. 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.

This Guide is intended to assist software developers who want to develop applications using the Cloud Databases API. It assumes the reader has a general understanding of databases and is familiar with: 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 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. Using this API document, your Rackspace Cloud account, and at least one Cloud Server, you can get started whenever you'd like. See the Getting Started with Rackspace Cloud Databases and Servers at http://docs.rackspace.com/ for information about getting started using the API. Please visit our Product Feedback Forum and let us know what you 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.

Cloud Databases is part of the Rackspace Cloud and your use through the API will be billed as per the pricing schedule at http://www.rackspace.com/cloud/public/databases/pricing. The Service Level Agreement (SLA) for Cloud Databases is available at http://www.rackspace.com/cloud/legal/sla/#cloud_databases.

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 shared Internet Small Computer System Interface (iSCSI) storage area networks (SAN) that provide for increased performance, scalability, availability and manageability. Applications with high I/O demands are performance optimized and data is protected through both local and network RAID-10. Additionally, network RAID provides synchronous replication of volumes with automatic failover and load balancing across available storage clusters.

The Cloud Databases API is implemented using a ReSTful web service interface. Like other products in the Rackspace Cloud suite, the Database Service shares a common token-based authentication system that allows seamless access between products and services. All requests to authenticate against and operate the service are performed using SSL over HTTP (HTTPS) on TCP port 443.

Every ReST request against the Database Service requires the inclusion of a specific authorization token, supplied by the X-Auth-Token HTTP header. Customers obtain this token by first using the Rackspace Cloud Authentication Service and supplying a valid username and API access key.

The Rackspace Cloud Authentication Service serves as the entry point to all Rackspace Cloud APIs and is itself a ReSTful web service. To access the Authentication Service, you must know whether your account is US-based or UK-based: US-based accounts authenticate through &ENDPOINT-US-20;. UK-based accounts authenticate through &ENDPOINT-UK-20;. Your account may be based in either the US or the UK; this is not determined by your physical location but by the location of the Rackspace retail site which was used to create your account: If your account was created via http://www.rackspacecloud.com, it is a US-based account. If your account was created via http://www.rackspace.co.uk, it is a UK-based account. If you are unsure how your account was created, use the Rackspace contact information at either site to ask for help.

&POST; v2.0/tokens Authenticate to receive a token and a service catalog. Normal Response Code(s): 200, 203 Error Response Code(s): unauthorized (401), userDisabled (403), badRequest (400), authFault (500), serviceUnavailable (503) The authenticate operation provides clients with an authentication token and a list of regional cloud endpoints. The sample requests and responses in this section illustrate a general case. In your authentication request, use your own credentials rather than the sample values shown here for username and apiKey. When you authenticate successfully, the response to your authentication request will include a catalog of the services to which you have subscribed rather than the sample values shown here. The username supplied here is your common Rackspace Cloud username. The key is your API access key. The key can be obtained from the Rackspace Cloud Control Panel in the <Your Account>/API Access section (login here: Control Panel Login). The information shown in the Auth Response examples is for US-based accounts. If you authenticate against the UK-endpoint for auth, you will see the service catalog information for UK-based accounts. In XML responses only, a list of namespaces identifies API extensions that add functionality to the core API. This token can be presented to a service as evidence of authentication. Tokens are valid for a finite duration; a token's default lifespan is twenty-four hours. The token's expires attribute denotes the time after which the token will automatically become invalid. A token may be manually revoked before the time identified by the expires attribute; expires predicts a token's maximum possible lifespan but does not guarantee that it will reach that lifespan. Clients are encouraged to cache a token until it expires. Users can be assigned multiple roles, with each role providing specific privileges. In this example, jsmith is the administrative user for the account, holding the fully-privileged identity:admin role. Other users might hold other roles with different privileges. Roles need not be associated with actual job functions such as Administrator, Operator, Developer, Tester, or Trainer. The service catalog lists the services this user can access. In this example, the user can access one database service, one loadbalancing service, two compute services (Cloud Servers OpenStack and Cloud Servers), two object storage services (Cloud Files Content Distribution Network (CDN), and Cloud Files), and one DNS service. The catalog listing for each service provides at least one endpoint URL for that service. Other information, such as regions, versions, and tenants, is provided if it's relevant to this user's access to this service. The service type attribute identifies services that perform similar functions, whatever those services might be named. In this example, the services named cloudServers and cloudServersOpenstack are both identified as type="compute", identifying them as compute services even though the word "compute" does not appear in their names. Use service type as the primary value for locating a service. If multiple endpoints of the same service type exist in the same region, use service name as the tiebreaker. The service name attribute identifies each unique service in the catalog. Once a service is created, its name does not change. However, new services of the same service type may be added to the catalog with new names. If you are programmatically parsing an authentication response, use service type rather than service name as the basis for determining whether a user has access to a particular kind of service. Service type is stable across all releases; new service types may be developed, but existing service types are not renamed. In this example, type="compute" identifies all the available compute services, one of which is named cloudServers and one of which is named cloudServersOpenStack. New compute service names may be added in future releases; whatever the compute services are named, you can always recognize them by parsing for type="compute" in the authentication response's service catalog. A service may expose endpoints in different regions. Regional endpoints allow clients to provision resources in a manner that provides high availability. Some services are not region-specific. These services supply a single non-regional endpoint and do not provide access to internal URLs. Some services recognize specification of a tenant. If a service does recognize tenants, the format of the tenant specification is defined only by the service; for details about whether and how to specify a tenant, check the documentation for the service you are using. An endpoint can be assigned public and internal URLs. A public URL is accessible from anywhere. Access to a public URL usually incurs traffic charges. Internal URLs are only accessible to services within the same region. Access to an internal URL is free of charge. Authentication tokens are typically valid for 24 hours. Applications should be designed to re-authenticate after receiving a 401 (Unauthorized) response from a service endpoint. If you are programmatically parsing an authentication response, please be aware that service names are stable for the life of the particular service and can be used as keys. You should also be aware that a user's service catalog can include multiple uniquely-named services which perform similar functions. For example, cloudServersOpenStack is the OpenStack version of compute whereas cloudServers is the legacy version of compute; the same user can have access to both services. In Auth 2.0, the service type attribute can be used as a key by which to recognize similar services; see the tip below. Beginning with Auth 2.0, the service catalog includes a service type attribute to identify services that perform similar functions but have different names; for example, type="compute" identifies compute services such as cloudServers and cloudServersOpenStack. Some developers have found the service type attribute to be useful in parsing the service catalog. For additional information on Auth 2.0 (also known as the Cloud Identity Service), refer to the Cloud Identity Client Developer Guide at http://docs.rackspace.com/. Databases service endpoints are published in the service catalog in the Auth response with the account number, which is a required element of the service endpoints. The examples shown here are for authentication for US customers. Customers with UK-based accounts will see different values in the service catalog. Refer to the next section for more information about service endpoints.

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. You can find the available service access/endpoints for Cloud Databases summarized in the table below.

Regionalized Service Endpoints

Region		Endpoint
Chicago (ORD)		https://ord.databases.api.rackspacecloud.com/v1.0/1234/
Dallas/Ft. Worth (DFW)		https://dfw.databases.api.rackspacecloud.com/v1.0/1234/
London (LON)		https://lon.databases.api.rackspacecloud.com/v1.0/1234/

Replace the sample account ID number, 1234, 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. For example, in you can see from the publicURL field for cloudServers ("https://servers.api.rackspacecloud.com/v1.0/1100111") that the account number is 1100111.

The Cloud Databases version defines the contract and build information for the API.

The contract version denotes the data model and behavior that the API supports. The requested contract version is included in all request URLs. Different contract versions of the API may be available at any given time and are not guaranteed to be compatible with one another. https://ord.databases.api.rackspacecloud.com/v1.0/1234 This document pertains to contract version 1.0.

The API List Versions call is available to show the current API version as well as information about all versions of the API. Refer to for details.

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.

Reviewer: I am hiding this entire section for the Private Beta, since I'm not sure that it applies. Is that correct? 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

Reviewer: I am hiding this entire section for the Private Beta, since I'm not sure that it applies. Is that correct? 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			50

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

To reduce load on the service, list operations return a maximum of 20 items at a time. This is referred to as pagination. Cloud Databases has separate paging limits for instances, databases, and users, which are currently all set to 20. If a request supplies no limit or one that exceeds the configured default limit, the default is used instead. Pagination provides the ability to limit the size of the returned data as well as retrieve a specified subset of a large data set. Pagination has two key concepts: limit and marker. Limit is the restriction on the maximum number of items for that type that can be returned. Marker is the ID of the last item in the previous list returned. The ID is the UUID in the case of instances, and the name in the case of databases and users. For example, a query could request the next 10 instances after the instance "1234" as follows: ?limit=10&marker=1234. Items are displayed sorted by ID. Pagination applies only to the calls listed in the following table: Verb URI Description &GET; /instances/ Lists the status and information for all database instances. &GET; /instances/{instanceId}/databases Lists databases for the specified instance. &GET; /instances/{instanceId}/users Lists the users in the specified database instance. If the content returned by a call is paginated, the response includes a structured link much like an instance item's links, with the basic structure {"href": "<url>", "rel": "next"}. Any response that is truncated by pagination will have a next link, which points to the next item in the collection. If there are no more items, no next link is returned. See the examples of paged List Instances calls that follow. Notice that the paged request examples above set the limit to 2 (?limit=2), so the responses that follow each show 2 instances and return a marker set to the UUID of the last item in the returned list (?marker=4137d6a4-03b7-4b66-b0ef-8c7c35c470d3). Also a link is provided to retrieve the next 2 results (limit=2) in the link element identified by the attribute rel="next" (XML) or "rel":"next" (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.

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), please call support for assistance. ERROR – The last operation for the database instance failed due to an error.

Database instances are directly accessible only on the internal ServiceNet network and using a Cloud resource within the same regional datacenter. For example, a database instance in DFW can only be accessed by a Cloud Server in DFW. Note that using a public Cloud Load Balancer allows you to access your ServiceNet database instance from the public network by performing the following steps: Using the Cloud Databases API, create a database instance. For details see . Using the Cloud Load Balancers API, create a public load balancer and specify your database instance hostname as a node, or use the API to add your instance hostname as a node to an existing public load balancer. For details refer to the Cloud Load Balancers Developer Guide at http://docs.rackspace.com/api/.

Do not use trailing slashes (/) at the end of calls to API operations, since this may cause the call to fail. For example, do not use &GET; /instances/detail/ (with the trailing slash at the end). Rather, use &GET; /instances/detail instead.

This section describes the versions that are supported for the Cloud Databases API.

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

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

This section describes the operations that are supported for databases.

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

This section describes the operations that are supported for flavors.

database A MySQL database within a database instance. database instance A database instance is an isolated MySQL instance in a single tenant environment on a shared physical host machine. Also referred to as instance. 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 shared Internet Small Computer System Interface (iSCSI) storage area networks (SAN) that provide for increased performance, scalability, availability and manageability. Applications with high I/O demands are performance optimized and data is protected through both local and network RAID-10. Additionally, network RAID provides synchronous replication of volumes with automatic failover and load balancing across available storage clusters.