# OpenStack Cloud Databases Developer Guide

OpenStack Cloud Databases Developer Guide
OpenStack LLC
2010 2011 2012 2013 OpenStack LLC
API v1.0
OpenStack Cloud Databases
Copyright details are filled in by the template.

This document is intended for software developers interested in developing applications using the OpenStack Cloud Databases Application Programming Interface (API).

2013-05-02

- This document is for the initial OpenStack review.

this is a placeholder for the front cover

this is a placeholder for the back cover

API Developer Guide cdb 20

## Overview

OpenStack Cloud Databases is an OpenStack-based MySQL relational database service that allows customers to easily provision database instances of varying virtual resource sizes without the need to maintain and/or update MySQL. Interactions with Cloud Databases occur programmatically via the Cloud Databases API as described in this developer guide.

OpenStack 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:

Reviewer: need to edit graphic above so it says "The Cloud" rather than "The Rackspace Cloud".

### Intended Audience

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 data serialization 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

You can download the most current versions of this and other API-related documents from http://docs.openstack.org/.

We welcome feedback, comments, and bug reports at https://bugs.launchpad.net/reddwarf.

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:

### 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 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.

## General API Information

The Cloud Databases API is implemented using a ReSTful web service interface. Like other cloud products, the Database Service shares a common token-based authentication system that allows seamless access between products and services.

All requests to authenticate against and operate the service are performed using SSL over HTTP (HTTPS) on TCP port 443.

### Authentication

Each HTTP request against the Cloud Database service requires the inclusion of specific authentication credentials. A single deployment may support multiple authentication schemes (OAuth, Basic Auth, Token). The authentication scheme used is determined by the provider of the Cloud Database service. Please contact your provider to determine the best way to authenticate against this API.

Some authentication schemes may require that the API operate using SSL over HTTP (HTTPS).

### Cloud Databases Service Versions

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

#### Contract Version

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.

Example Request URL (contract version in bold)

    https://ord.databases.api.rackspacecloud.com/v1.0/1234

This document pertains to contract version 1.0.

#### API Version

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.

### 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

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.

Reviewer: Need new examples that show OpenStack host.

List Instances Paged Request: JSON

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 `"rel":"next"`:

List Instances Paged Response: JSON

    HTTP/1.1 200 OK
    Content-Type: application/json
    Via: 1.1 Repose (Repose/2.6.7)
    Content-Length: 1172
    Date: Mon, 18 Mar 2013 19:09:17 GMT
    Server: Jetty(8.0.y.z-SNAPSHOT)

### Faults

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 Fault Response: JSON

    HTTP/1.1 500 Internal Server Error
    Content-Length: 120
    Content-Type: application/json; charset=UTF-8
    Date: Tue, 29 Nov 2011 00:33:48 GMT

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: JSON

    HTTP/1.1 400 None
    Content-Length: 120
    Content-Type: application/json; charset=UTF-8
    Date: Tue, 29 Nov 2011 00:33:48 GMT

The next two examples show `itemNotFound` errors:

Example itemNotFound Fault: JSON

    HTTP/1.1 404 Not Found
    Content-Length: 78
    Content-Type: application/json; charset=UTF-8
    Date: Tue, 29 Nov 2011 00:35:24 GMT

#### Synchronous Versus Asynchronous Faults

Synchronous faults occur at request time. When a synchronous fault occurs, the fault contains an HTTP error response code, a human readable message, and optional details about the error. The following Database API calls are synchronous and may produce synchronous faults:

- List Users

- List Instances

- List Instance Details by ID

- List Databases

- Enable Root User

- List Root-Enabled Status

- List Flavors

- List Versions

- List Version Details

Asynchronous faults occur in the background while an instance, database, or user is being built or an instance is executing an action. When an asynchronous fault occurs, the system places the instance, database, or user in an ERROR state and embeds the fault in the offending instance, database, or user. When an asynchronous fault occurs, the fault contains an HTTP error response code, a human readable message, and optional details about the error. The following Database API calls are asynchronous and may produce asynchronous faults:

- Create Instance

- Delete Instance

- Create Database

- Delete Database

- Create User

- Delete User

- Resize Volume

- Resize Instance

- Restart Instance

Note that an asynchronous operation, if it fails, may not give the user an error, and the operation can error out without a failure notification.

### 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), please call support for assistance.

- ERROR – The last operation for the database instance failed due to an error.

## API Operations

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.

### API Versions

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

### Database Instances

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

### Database Instance Actions

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

### Databases

This section describes the operations that are supported for databases.

### Users

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

In this section, "user has access to a database" means that the user has full create, read, update, and delete access to the given database. In other words, on a cloud database instance, a user named USER and a database named DATABASE exist, and within MySQL, a GRANT ALL ON DATABASE.* TO USER has been issued on the instance.

There is a bug in a python library that development is using that may cause incorrect user deletions to occur if a period (.) is used in the user name. In this case, the user name is truncated to remove the portion of the name from the period to the end, leaving only the portion from the beginning up to the period. For example, for a user named "my.userA", the bug would truncate the user name to "my", and if the user "my" exists, that user will be incorrectly deleted. To avoid the problem, do not use periods in user names.

### Flavors

This section describes the operations that are supported for flavors.

## Glossary

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.