GET'> PUT'> POST'> DELETE'> MAY'> SHOULD'> MUST'> MUST NOT'> ]> Rackspace Cloud Databases and Servers Getting Started Guide 2011 2012 Rackspace US, Inc. API v1.0 Rackspace Cloud Databases 2012-09-04 Copyright details are filled in by the template. 2012-09-04 Added information for pricing and service level (refer to ). 2012-08-02 Corrected request examples for authentication (refer to ). 2012-08-01 Initial Unlimited Availability (UA) release for Rackspace Cloud Databases. cdb 1 This version of the Getting Started replaces and obsoletes all previous versions. The most recent changes are described in the table below: Follow the steps described in this guide to use the Rackspace Cloud Databases API and the Cloud Servers section of the Rackspace Cloud Control Panel to create and access your database instances via Rackspace Cloud Servers. For details about using the Cloud Databases API, refer to the Cloud Databases Developer Guide at 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. Please visit our Product Feedback Forum and let us know what you think about Cloud Databases!

In order to run the examples in this guide, you must have the following prerequisites: Rackspace Cloud account Rackspace Cloud username and password, as specified during registration

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. Cloud Servers is also part of the Rackspace Cloud and your use through the Control Panel will be billed as per the pricing schedule at http://www.rackspace.com/cloud/public/servers/pricing. The Service Level Agreements (SLAs) for Cloud Databases and Cloud Servers are available at http://www.rackspace.com/cloud/legal/sla/#cloud_databases and http://www.rackspace.com/cloud/legal/sla respectively.

You have several options for sending requests through an API: Developers and testers may prefer to use cURL, the command-line tool from http://curl.haxx.se/. With cURL you can send HTTP requests and receive responses back from the command line. If you like to use a more graphical interface, the ReST client for Firefox also works well for testing and trying out commands, see https://addons.mozilla.org/en-US/firefox/addon/restclient/. You can also download and install rest-client, a Java application to test ReSTful web services, from http://code.google.com/p/rest-client/.

cURL is a command-line tool that is available on most UNIX®-like environments and Mac OS X® and can be downloaded for Windows® in order to interact with the ReST interfaces. For more information on cURL, visit http://curl.haxx.se/. cURL allows you to transmit and receive HTTP requests and responses from the command-line or from within a shell script. This makes it possible to work with the ReST API directly without using one of the client APIs. The following cURL command-line options will be used in this guide to run the examples: -d Sends the specified data in a post request to the HTTP server. -i Includes the HTTP header in the output. -H HEADER Specify an HTTP header in the request. If you have the tools, you can run the cURL JSON request examples with the following options to format the output from cURL: <curl JSON request example> | python -mjson.tool.

To run the cURL request examples shown in this guide on Linux or Mac systems, copy and paste each example from the HTML version of this guide into an ASCII editor (for example vi or TextEdit). Then modify each example with your required account information and so forth, as detailed in this guide. The carriage returns in the cURL request examples that are part of the cURL syntax are escaped with a backslash ('\') in order to avoid prematurely terminating the command. However you should not escape carriage returns inside the xml or json message within the command. Consider the following cURL Authenticate Request: XML example that is described in detail in : curl -i -d \ '<?xml version="1.0" encoding="UTF-8"?> <auth>    <apiKeyCredentials      xmlns="http://docs.rackspace.com/identity/api/ext/RAX-KSKEY/v1.0"      username="your_username"      apiKey="your_api_key"/>    </auth>' \ 'https://identity.api.rackspacecloud.com/v2.0/tokens' You can see that the lines that are part of the cURL command syntax have all been escaped with a backslash ('\') to indicate that the command continues on the next line: curl -i -d \    (... lines within the xml portion of the message are not shown in this example) (... the example only shows lines that are part of cURL syntax)                   </auth>' \ 'https://identity.api.rackspacecloud.com/v2.0/tokens' However the lines within the xml portion of the message are not escaped with a backslash ('\') in order to avoid issues with the xml processing: '<?xml version="1.0" encoding="UTF-8"?> <auth>    <apiKeyCredentials      xmlns="http://docs.rackspace.com/identity/api/ext/RAX-KSKEY/v1.0"      username="your_username"      apiKey="your_api_key"/>    </auth>' \ The final line of the xml message is escaped since the backslash lies outside the xml message and continues the cURL command to the next line. After you are finished modifying the text for the cURL request example with your information (for example your_username and your_api_key), paste it into your terminal window. Then execute the cURL command by pressing Enter. If you have trouble copying and pasting the examples as described, try typing the entire example on one long line, removing all the backslash line continuation characters.

You need to generate a token whether you use cURL or a ReST client. In order to use the ReST API, you will first need to obtain an authentication token, which will need to be passed in for each request using the X-Auth-Token header. The following example demonstrates how to use cURL to obtain the authentication token and the account number. You will need to supply the authentication token and account number when making subsequent Cloud Databases API calls. Remember to replace the names in the Authenticate Request examples below with their respective values: your_username — The username is your common Rackspace Cloud username, as supplied during registration. your_api_key — The key is your API access key. The key can be obtained from the Rackspace Cloud Control Panel in the <Your Account> / API Keys section (login here: Control Panel Login). 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. Notice that you authenticate using a special URL for Cloud authentication services. For example, for US-based accounts, you use https://identity.api.rackspacecloud.com/v2.0/tokens, as shown in the following Authenticate Request examples. Note that the v2.0 component in the URL indicates that you are using version 2.0 of the Cloud Auth API. curl -i -d \ '<?xml version="1.0" encoding="UTF-8"?> <auth> <apiKeyCredentials xmlns="http://docs.rackspace.com/identity/api/ext/RAX-KSKEY/v1.0" username="your_username" apiKey="your_api_key"/> </auth>' \ -H 'Content-Type: application/xml' \ -H 'Accept: application/xml' \ 'https://identity.api.rackspacecloud.com/v2.0/tokens' curl -i -d \ '{ "auth": { "RAX-KSKEY:apiKeyCredentials": { "username": "your_username", "apiKey": "your_api_key"} } }' \ -H 'Content-Type: application/json' \ 'https://identity.api.rackspacecloud.com/v2.0/tokens' For UK-based accounts, you would need to modify the URL shown in the last line of each of the Authenticate Request examples above to be 'https://lon.identity.api.rackspacecloud.com/v2.0/tokens' instead. Missing code sample! Missing code sample! The authentication token id is returned along with an expires attribute that specifies when the token expires. For all response examples in this guide, the field values you receive in your responses will vary from those shown here since they will be specific to your account. The information shown in the Authenticate Response examples above 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. The id attribute in the Authenticate Response specifies the authentication token. Tokens are valid for a finite duration. Remember to supply your authentication token wherever you see the field your_auth_token in the examples in this guide. The 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. Applications should be designed to re-authenticate after receiving a 401 (Unauthorized) response from a service endpoint. The publicURL endpoints for cloudDatabases (for example https://ord.databases.api.rackspacecloud.com/v1.0/1100111) are also returned in the response. You will find the actual account number after the final '/' in the publicURL field. In this example, you can see that the account number is 1100111. You need to specify your account number on most of the Cloud Databases API calls, wherever you see the field your_acct_id specified in the examples in this guide. After authentication, you can use cURL to perform &GET;, &DELETE;, and &POST; requests for the Cloud Databases API. The endpoints to use for your Cloud Databases API calls are 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/

Choose the endpoint from the table for the datacenter where your Cloud resources are located. The Cloud Server that you use in must be located in the same datacenter where your database resides. All examples in this guide assume that you are operating against the ORD datacenter, however if you are using a different datacenter, be sure to use the associated endpoint from the table above instead. Replace the sample account ID number, 1234, with your actual account number returned as part of the authentication response. Use your actual account number wherever you see the field your_acct_id specified in this guide. Refer to . When making a Cloud Databases API call, place the endpoint at the beginning of the request URL, for example: (https://ord.databases.api.rackspacecloud.com/v1.0/your_acct_id/), as you can see in the cURL List Flavors Details Request examples in . 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. The larger the flavor size you use, the larger the amount of RAM and priority for CPU time your database instance will receive. You need to use the List Flavors API call (/flavors) to find the available configurations for your database instance, and then decide which size you need. This operation does not require a request body. The following examples show the cURL requests for List Flavors: curl -i \ -H 'X-Auth-Token: your_auth_token' \ -H 'Accept: application/xml' \ 'https://ord.databases.api.rackspacecloud.com/v1.0/your_acct_id/flavors' curl -i \ -H 'X-Auth-Token: your_auth_token' \ -H 'Accept: application/json' \ 'https://ord.databases.api.rackspacecloud.com/v1.0/your_acct_id/flavors' Remember to replace the names in the examples above with their actual respective values for all the cURL examples that follow: your_auth_token — as returned in your authentication response (see the response examples in ) your_acct_id — as returned in your authentication response (must be replaced in the request URL) The following examples show the responses for List Flavors: Missing code sample! Missing code sample! In the previous examples, you can see from the flavor name that there are multiple flavors available, including medium (with 1 virtual CPU and 2 gigabytes of memory) and tiny (with 1 virtual CPU and 0.5 gigabytes of memory). In this example, assume that you decide to use the tiny flavor (id 1) to provide the needed capacity for your database instance. Notice that there are two kinds of link relations associated with flavor resources. A self link contains a versioned link to the flavor resource. These links should be used in cases where the link will be followed immediately (as you will see in the next section). A bookmark link provides a permanent link to a flavor resource that is appropriate for long term storage and works across API versions. A database instance is an isolated MySQL instance in a single tenant environment on a shared physical host machine. In the example below, you create a database instance with a database and a user. The example instance uses the tiny flavor and a volume size of 2 gigabytes (GB). Refer to Create Database in the Cloud Databases Developer Guide for the restrictions for choosing the database name. The example creates a database instance myrackinstance, with the following: the tiny flavor volume size of 2 gigabytes (GB) a database named sampledb with: utf8 character set utf8_general_ci collation a user simplestUser with password password Notice that the request specifies the flavor reference (flavorRef) to the tiny flavor (id 1) that was returned by the List Flavors Details call: "https://ord.databases.api.rackspacecloud.com/v1.0/1234/flavors/1". This is the self link that is the versioned link to the flavor resource. Refer to the response examples in . The following examples show the cURL requests for Create Instance: curl -i -d \ '<?xml version="1.0" ?> <instance xmlns="http://docs.openstack.org/database/api/v1.0" name="myrackinstance" flavorRef= "https://ord.databases.api.rackspacecloud.com/v1.0/your_acct_id/flavors/1"> <databases> <database name="sampledb" character_set="utf8" collate="utf8_general_ci" /> </databases> <users> <user name="simplestUser" password="password"> <databases> <database name="sampledb"/> </databases> </user> </users> <volume size="2" /> </instance>' \ -H 'X-Auth-Token: your_auth_token' \ -H 'Content-Type: application/xml' \ -H 'Accept: application/xml' \ 'https://ord.databases.api.rackspacecloud.com/v1.0/your_acct_id/instances' curl -i -d \ '{ "instance": { "databases": [ { "character_set": "utf8", "collate": "utf8_general_ci", "name": "sampledb" } ], "flavorRef": "https://ord.databases.api.rackspacecloud.com/v1.0/your_acct_id/flavors/1", "name": "myrackinstance", "users": [ { "databases": [ { "name": "sampledb" } ], "name": "simplestUser", "password": "password" } ], "volume": { "size": 2 } } }' \ -H 'X-Auth-Token: your_auth_token' \ -H 'Content-Type: application/json' \ 'https://ord.databases.api.rackspacecloud.com/v1.0/your_acct_id/instances' Remember to replace the names in the examples above with their actual respective values for all the cURL examples that follow: your_auth_token — as returned in your authentication response (see the response examples in ) your_acct_id — as returned in your authentication response (must be replaced in the request URL) Remember to replace the account id shown in the flavorRef property for the examples with your actual account id: "https://ord.databases.api.rackspacecloud.com/v1.0/your_acct_id/flavors/1". Rather than the flavor URI shown in the previous sentence, you can also pass the flavor id (integer) as the value for flavorRef. For example, the flavor id for the flavor URI shown above is "1". The following examples show the Create Instance responses: Missing code sample! Missing code sample! You will need to specify the instance id returned (in the response examples above: id="d379ba5c-9a1f-4aa9-9a17-afe237d04c65") on subsequent API calls that require it, for example List Databases for Instance. Note that the database and user are not listed in the Create Instance responses. Next you will verify that both were successfully created. The operation of creating the database instance may take up to several minutes. You will not be able to perform the operations to List Databases for Instance and List Users for Instance in the sections that follow until the instance has ACTIVE status. In this section you will list the databases in the specified database instance. This operation does not require a request body. The following examples show the cURL requests for List Databases for Instance: curl -i \ -H 'X-Auth-Token: your_auth_token' \ -H 'Content-Type: application/xml' \ -H 'Accept: application/xml' \ 'https://ord.databases.api.rackspacecloud.com/v1.0/your_acct_id/instances/instance_id/databases' curl -i \ -H 'X-Auth-Token: your_auth_token' \ -H 'Content-Type: application/json' \ 'https://ord.databases.api.rackspacecloud.com/v1.0/your_acct_id/instances/instance_id/databases' Remember to replace the names in the examples above with their actual respective values: your_auth_token — as returned in your authentication response (see the examples in ) your_acct_id — as returned in your authentication response (see the examples in ) instance_id — as returned in your create instance response (see the examples in ) The following examples show the responses for Create User: HTTP/1.1 200 OK Content-Type: application/xml Content-Length: 109 Date: Thu, 05 Apr 2012 18:20:18 GMT <databases xmlns="http://docs.openstack.org/database/api/v1.0"> <database name="sampledb"/> </databases> HTTP/1.1 200 OK Content-Type: application/json Content-Length: 37 Date: Thu, 05 Apr 2012 18:13:53 GMT { "databases": [ { "name": "sampledb" } ] } You can see that the database sampledb was successfully created. Next you will list the users. In this section you will list the users in the specified database instance. This operation does not require a request body. The following examples show the cURL requests for List Users in Database Instance: curl -i \ -H 'X-Auth-Token: your_auth_token' \ -H 'Content-Type: application/xml' \ -H 'Accept: application/xml' \ 'https://ord.databases.api.rackspacecloud.com/v1.0/your_acct_id/instances/instance_id/users' curl -i \ -H 'X-Auth-Token: your_auth_token' \ -H 'Content-Type: application/json' \ 'https://ord.databases.api.rackspacecloud.com/v1.0/your_acct_id/instances/instance_id/users' Remember to replace the names in the examples above with their actual respective values: your_auth_token — as returned in your authentication response (see the examples in ) your_acct_id — as returned in your authentication response (see the examples in ) instance_id — as returned in your create instance response (see the examples in ) The following examples show the responses for List Users in Database Instance: HTTP/1.1 200 OK Content-Type: application/xml Content-Length: 109 Date: Thu, 05 Apr 2012 18:20:18 GMT <?xml version="1.0" ?> <users xmlns="http://docs.openstack.org/database/api/v1.0"> <user name="simplestUser"> <databases> <database> <name> sampledb </name> </database> </databases> </user> </users> HTTP/1.1 200 OK Content-Type: application/json Content-Length: 113 Date: Thu, 05 Apr 2012 18:13:53 GMT { "users": [ { "databases": [ { "name": "sampledb" } ], "name": "simplestUser" } ] } You can see that the user simplestUser was successfully created. Create a Cloud Server (or use an existing Cloud Server) to access your database. If you are using an existing Cloud Server on your account, skip this step and go directly to . Create a Cloud Server using the Cloud Servers section of the Cloud Control Panel (login here: Control Panel Login). Click Servers to view the Cloud Servers page. Using the Region drop-down menu, select the appropriate region, depending on whether you want to create a first generation Cloud Server or a next generation Cloud Server. (The type of Cloud Server does not matter for this exercise.) Select an image from a list of different operating systems, including Linux Distributions and Windows Images: Specify the Server Name and select a Size for your Cloud Server, then click Create Server. You can also create a Cloud Server using the Cloud Servers API. Refer to the Next Generation Cloud Servers Developer Guide for details. If you are configuring an application to use your database on a Cloud Server, you need to configure the application with the hostname for the database instance and user name / password for the database. Refer to the response examples in for the hostname returned and the request examples for the user name and password you specified. If you want to access your database using the command line MySQL client, then you have now completed the Getting Started. Otherwise, you can use a GUI tool such as phpMyAdmin to interact with your database instance. Common operations include managing databases, tables, fields, relations, indexes, users, and permissions. Included below is a procedure to set up phpMyAdmin on an Ubuntu 11.04 Cloud Server. For more detailed installation configuration instructions see the phpMyAdmin documentation at: http://www.phpmyadmin.net/documentation/. Rackspace does not provide phpMyAdmin support, and the user is responsible for any security related configuration. Install phpMyAdmin: sudo apt-get install phpmyadmin Set up a symbolic link to the phpmyadmin config file: sudo ln -s /etc/phpmyadmin/apache.conf /etc/apache2/conf.d/phpmyadmin.conf Edit the /etc/phpmyadmin/config-db.php config file to point to your database instance: $dbserver='<cloud database hostname>'; Restart apache: sudo apachectl restart Access phpMyAdmin at http://<your_ipaddress>/phpMyAdmin: This concludes the Getting Started. Thank you for using Rackspace Cloud products.