summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJenkins <jenkins@review.openstack.org>2017-07-16 11:28:09 +0000
committerGerrit Code Review <review@openstack.org>2017-07-16 11:28:09 +0000
commitfa171bd3e92d7d7b9032fc035f554dcb4621ce94 (patch)
tree7b3a83aeebe1fc72f76e0446120c926393e365bd
parentc60262f6b8b5fffbfff8a4f1052949676f54f09a (diff)
parentdaee6f3fe6444440f0fe0b4f99c283d82faf7954 (diff)
Merge "Remoe obsolete apidocs"8.0.0.0b3
-rw-r--r--integration/.gitignore25
-rw-r--r--integration/apidocs/pom.xml193
-rw-r--r--integration/apidocs/src/resources/cdb-devguide.xml1675
-rw-r--r--integration/apidocs/src/resources/cdb-getting-started.xml1131
-rw-r--r--integration/apidocs/src/resources/cdb-mgmt-devguide.xml1267
-rw-r--r--integration/apidocs/src/resources/cdb-releasenotes.xml711
-rw-r--r--integration/apidocs/src/resources/images/Choose_CS_Image.pngbin85201 -> 0 bytes
-rw-r--r--integration/apidocs/src/resources/images/Choose_CS_Image_CCP.pngbin24996 -> 0 bytes
-rw-r--r--integration/apidocs/src/resources/images/Choose_Image_CCP.pngbin21253 -> 0 bytes
-rw-r--r--integration/apidocs/src/resources/images/Choose_Image_CCP.tiffbin26244 -> 0 bytes
-rw-r--r--integration/apidocs/src/resources/images/Cloud_DB_Infographic-1.pngbin66336 -> 0 bytes
-rw-r--r--integration/apidocs/src/resources/images/Cloud_DB_Infographic-1.svg4533
-rw-r--r--integration/apidocs/src/resources/images/Create_CS.pngbin31902 -> 0 bytes
-rw-r--r--integration/apidocs/src/resources/images/phpMyAdmin.pngbin257577 -> 0 bytes
-rw-r--r--integration/apidocs/src/resources/samples/db-auth-20.json128
-rw-r--r--integration/apidocs/src/resources/samples/db-auth-20.xml63
-rw-r--r--integration/apidocs/src/resources/samples/db-auth.json72
-rw-r--r--integration/apidocs/src/resources/samples/db-auth.xml50
-rw-r--r--integration/apidocs/src/resources/samples/db-check-root-user-request.json8
-rw-r--r--integration/apidocs/src/resources/samples/db-check-root-user-request.xml8
-rw-r--r--integration/apidocs/src/resources/samples/db-check-root-user-response.json8
-rw-r--r--integration/apidocs/src/resources/samples/db-check-root-user-response.xml6
-rw-r--r--integration/apidocs/src/resources/samples/db-create-database-instance-response.json41
-rw-r--r--integration/apidocs/src/resources/samples/db-create-database-instance-response.xml24
-rw-r--r--integration/apidocs/src/resources/samples/db-create-databases-request.json19
-rw-r--r--integration/apidocs/src/resources/samples/db-create-databases-request.xml13
-rw-r--r--integration/apidocs/src/resources/samples/db-create-databases-response.json4
-rw-r--r--integration/apidocs/src/resources/samples/db-create-databases-response.xml4
-rw-r--r--integration/apidocs/src/resources/samples/db-create-instance-request.json37
-rw-r--r--integration/apidocs/src/resources/samples/db-create-instance-request.xml23
-rw-r--r--integration/apidocs/src/resources/samples/db-create-instance-response.json41
-rw-r--r--integration/apidocs/src/resources/samples/db-create-instance-response.xml19
-rw-r--r--integration/apidocs/src/resources/samples/db-create-users-request.json32
-rw-r--r--integration/apidocs/src/resources/samples/db-create-users-request.xml21
-rw-r--r--integration/apidocs/src/resources/samples/db-create-users-response.json4
-rw-r--r--integration/apidocs/src/resources/samples/db-create-users-response.xml4
-rw-r--r--integration/apidocs/src/resources/samples/db-credentials-20.json18
-rw-r--r--integration/apidocs/src/resources/samples/db-credentials-20.xml14
-rw-r--r--integration/apidocs/src/resources/samples/db-credentials.json13
-rw-r--r--integration/apidocs/src/resources/samples/db-credentials.xml11
-rw-r--r--integration/apidocs/src/resources/samples/db-delete-databases-request.json8
-rw-r--r--integration/apidocs/src/resources/samples/db-delete-databases-request.xml8
-rw-r--r--integration/apidocs/src/resources/samples/db-delete-databases-response.json4
-rw-r--r--integration/apidocs/src/resources/samples/db-delete-databases-response.xml4
-rw-r--r--integration/apidocs/src/resources/samples/db-delete-instance-request.json8
-rw-r--r--integration/apidocs/src/resources/samples/db-delete-instance-request.xml8
-rw-r--r--integration/apidocs/src/resources/samples/db-delete-instance-response.json4
-rw-r--r--integration/apidocs/src/resources/samples/db-delete-instance-response.xml4
-rw-r--r--integration/apidocs/src/resources/samples/db-delete-users-request.json8
-rw-r--r--integration/apidocs/src/resources/samples/db-delete-users-request.xml8
-rw-r--r--integration/apidocs/src/resources/samples/db-delete-users-response.json4
-rw-r--r--integration/apidocs/src/resources/samples/db-delete-users-response.xml4
-rw-r--r--integration/apidocs/src/resources/samples/db-enable-root-user-request.json8
-rw-r--r--integration/apidocs/src/resources/samples/db-enable-root-user-request.xml8
-rw-r--r--integration/apidocs/src/resources/samples/db-enable-root-user-response.json11
-rw-r--r--integration/apidocs/src/resources/samples/db-enable-root-user-response.xml7
-rw-r--r--integration/apidocs/src/resources/samples/db-faults-badRequest.json11
-rw-r--r--integration/apidocs/src/resources/samples/db-faults-badRequest.xml10
-rw-r--r--integration/apidocs/src/resources/samples/db-faults-instanceFault.json11
-rw-r--r--integration/apidocs/src/resources/samples/db-faults-instanceFault.xml10
-rw-r--r--integration/apidocs/src/resources/samples/db-faults-itemNotFound.json11
-rw-r--r--integration/apidocs/src/resources/samples/db-faults-itemNotFound.xml10
-rw-r--r--integration/apidocs/src/resources/samples/db-flavors-by-id-request.json8
-rw-r--r--integration/apidocs/src/resources/samples/db-flavors-by-id-request.xml8
-rw-r--r--integration/apidocs/src/resources/samples/db-flavors-by-id-response.json22
-rw-r--r--integration/apidocs/src/resources/samples/db-flavors-by-id-response.xml11
-rw-r--r--integration/apidocs/src/resources/samples/db-flavors-request.json8
-rw-r--r--integration/apidocs/src/resources/samples/db-flavors-request.xml8
-rw-r--r--integration/apidocs/src/resources/samples/db-flavors-response.json69
-rw-r--r--integration/apidocs/src/resources/samples/db-flavors-response.xml32
-rw-r--r--integration/apidocs/src/resources/samples/db-gs-create-database-instance-response.json41
-rw-r--r--integration/apidocs/src/resources/samples/db-gs-create-database-instance-response.xml22
-rw-r--r--integration/apidocs/src/resources/samples/db-guest-update-request.json10
-rw-r--r--integration/apidocs/src/resources/samples/db-guest-update-request.xml10
-rw-r--r--integration/apidocs/src/resources/samples/db-guest-update-response.json6
-rw-r--r--integration/apidocs/src/resources/samples/db-guest-update-response.xml6
-rw-r--r--integration/apidocs/src/resources/samples/db-instance-reboot-request.json10
-rw-r--r--integration/apidocs/src/resources/samples/db-instance-reboot-request.xml10
-rw-r--r--integration/apidocs/src/resources/samples/db-instance-reboot-response.json6
-rw-r--r--integration/apidocs/src/resources/samples/db-instance-reboot-response.xml6
-rw-r--r--integration/apidocs/src/resources/samples/db-instance-resize-flavor-request.json12
-rw-r--r--integration/apidocs/src/resources/samples/db-instance-resize-flavor-request.xml10
-rw-r--r--integration/apidocs/src/resources/samples/db-instance-resize-flavor-response.json4
-rw-r--r--integration/apidocs/src/resources/samples/db-instance-resize-flavor-response.xml4
-rw-r--r--integration/apidocs/src/resources/samples/db-instance-resize-instance-request.json12
-rw-r--r--integration/apidocs/src/resources/samples/db-instance-resize-instance-request.xml12
-rw-r--r--integration/apidocs/src/resources/samples/db-instance-resize-instance-response.json6
-rw-r--r--integration/apidocs/src/resources/samples/db-instance-resize-instance-response.xml6
-rw-r--r--integration/apidocs/src/resources/samples/db-instance-resize-volume-request.json14
-rw-r--r--integration/apidocs/src/resources/samples/db-instance-resize-volume-request.xml12
-rw-r--r--integration/apidocs/src/resources/samples/db-instance-resize-volume-response.json4
-rw-r--r--integration/apidocs/src/resources/samples/db-instance-resize-volume-response.xml4
-rw-r--r--integration/apidocs/src/resources/samples/db-instance-restart-request.json10
-rw-r--r--integration/apidocs/src/resources/samples/db-instance-restart-request.xml9
-rw-r--r--integration/apidocs/src/resources/samples/db-instance-restart-response.json4
-rw-r--r--integration/apidocs/src/resources/samples/db-instance-restart-response.xml4
-rw-r--r--integration/apidocs/src/resources/samples/db-instance-status-detail-request.json8
-rw-r--r--integration/apidocs/src/resources/samples/db-instance-status-detail-request.xml8
-rw-r--r--integration/apidocs/src/resources/samples/db-instance-status-detail-response.json42
-rw-r--r--integration/apidocs/src/resources/samples/db-instance-status-detail-response.xml20
-rw-r--r--integration/apidocs/src/resources/samples/db-instance-update-guest-request.json11
-rw-r--r--integration/apidocs/src/resources/samples/db-instance-update-guest-request.xml10
-rw-r--r--integration/apidocs/src/resources/samples/db-instance-update-guest-response.json8
-rw-r--r--integration/apidocs/src/resources/samples/db-instance-update-guest-response.xml8
-rw-r--r--integration/apidocs/src/resources/samples/db-instances-index-pagination-request.json8
-rw-r--r--integration/apidocs/src/resources/samples/db-instances-index-pagination-request.xml8
-rw-r--r--integration/apidocs/src/resources/samples/db-instances-index-pagination-response.json45
-rw-r--r--integration/apidocs/src/resources/samples/db-instances-index-pagination-response.xml23
-rw-r--r--integration/apidocs/src/resources/samples/db-instances-index-request.json8
-rw-r--r--integration/apidocs/src/resources/samples/db-instances-index-request.xml8
-rw-r--r--integration/apidocs/src/resources/samples/db-instances-index-response.json71
-rw-r--r--integration/apidocs/src/resources/samples/db-instances-index-response.xml34
-rw-r--r--integration/apidocs/src/resources/samples/db-instances-paged-index-request.json8
-rw-r--r--integration/apidocs/src/resources/samples/db-instances-paged-index-request.xml8
-rw-r--r--integration/apidocs/src/resources/samples/db-instances-paged-index-response.json90
-rw-r--r--integration/apidocs/src/resources/samples/db-instances-paged-index-response.xml41
-rw-r--r--integration/apidocs/src/resources/samples/db-list-databases-request.json8
-rw-r--r--integration/apidocs/src/resources/samples/db-list-databases-request.xml8
-rw-r--r--integration/apidocs/src/resources/samples/db-list-databases-response.json24
-rw-r--r--integration/apidocs/src/resources/samples/db-list-databases-response.xml12
-rw-r--r--integration/apidocs/src/resources/samples/db-list-users-request.json8
-rw-r--r--integration/apidocs/src/resources/samples/db-list-users-request.xml8
-rw-r--r--integration/apidocs/src/resources/samples/db-list-users-response.json28
-rw-r--r--integration/apidocs/src/resources/samples/db-list-users-response.xml24
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-get-account-details-request.json8
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-get-account-details-request.xml8
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-get-account-details-response.json24
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-get-account-details-response.xml12
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-get-host-detail-request.json8
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-get-host-detail-request.xml8
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-get-host-detail-response.json29
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-get-host-detail-response.xml12
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-get-instance-details-request.json8
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-get-instance-details-request.xml8
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-get-instance-details-response.json51
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-get-instance-details-response.xml20
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-get-root-details-request.json8
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-get-root-details-request.xml8
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-get-root-details-response.json12
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-get-root-details-response.xml7
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-get-storage-request.json8
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-get-storage-request.xml8
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-get-storage-response.json23
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-get-storage-response.xml12
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-host-update-request.json12
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-host-update-request.xml10
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-host-update-response.json6
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-host-update-response.xml6
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-instance-diagnostics-request.json8
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-instance-diagnostics-request.xml8
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-instance-diagnostics-response.json16
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-instance-diagnostics-response.xml7
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-instance-hwinfo-request.json8
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-instance-hwinfo-request.xml8
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-instance-hwinfo-response.json13
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-instance-hwinfo-response.xml15
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-instance-index-request.json8
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-instance-index-request.xml8
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-instance-index-response.json89
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-instance-index-response.xml34
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-list-accounts-request.json8
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-list-accounts-request.xml8
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-list-accounts-response.json13
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-list-accounts-response.xml9
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-list-hosts-request.json8
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-list-hosts-request.xml8
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-list-hosts-response.json13
-rw-r--r--integration/apidocs/src/resources/samples/db-mgmt-list-hosts-response.xml9
-rw-r--r--integration/apidocs/src/resources/samples/db-request-types.json15
-rw-r--r--integration/apidocs/src/resources/samples/db-response-types.xml24
-rw-r--r--integration/apidocs/src/resources/samples/db-version-request.json8
-rw-r--r--integration/apidocs/src/resources/samples/db-version-request.xml8
-rw-r--r--integration/apidocs/src/resources/samples/db-version-response.json18
-rw-r--r--integration/apidocs/src/resources/samples/db-version-response.xml10
-rw-r--r--integration/apidocs/src/resources/samples/db-versions-request.json8
-rw-r--r--integration/apidocs/src/resources/samples/db-versions-request.xml8
-rw-r--r--integration/apidocs/src/resources/samples/db-versions-response.json20
-rw-r--r--integration/apidocs/src/resources/samples/db-versions-response.xml12
-rw-r--r--integration/xsd/common.ent72
-rw-r--r--integration/xsd/dbaas.wadl1177
-rw-r--r--integration/xsd/dbaas.xsd613
-rw-r--r--integration/xsd/management.wadl625
-rw-r--r--integration/xsd/management.xsd398
183 files changed, 0 insertions, 15026 deletions
diff --git a/integration/.gitignore b/integration/.gitignore
deleted file mode 100644
index 75bff19..0000000
--- a/integration/.gitignore
+++ /dev/null
@@ -1,25 +0,0 @@
1*.sublime-project
2*.sublime-workspace
3scripts/.screenrc
4scripts/test-def.conf
5.tox
6*.pyc
7*.coverage
8tests/integration/Reddwarf_Integration_Tests.egg-info/*
9apidocs/target
10scripts/.cache/
11scripts/.cinderclient/
12scripts/.mysql_history
13scripts/.troveclient/
14conf.json
15Vagrantfile
16.my.cnf
17.vagrant
18.bash_history
19.rnd
20options.rc
21.novaclient
22*.log
23.local.conf
24scripts/local.conf.d/local.conf.d
25*.config/
diff --git a/integration/apidocs/pom.xml b/integration/apidocs/pom.xml
deleted file mode 100644
index 9351619..0000000
--- a/integration/apidocs/pom.xml
+++ /dev/null
@@ -1,193 +0,0 @@
1<?xml version="1.0" encoding="UTF-8"?>
2<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
3 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
4 <modelVersion>4.0.0</modelVersion>
5
6 <groupId>com.rackspace.cloud.dbaas</groupId>
7 <artifactId>dbaas-docs</artifactId>
8 <version>1.0.0</version>
9
10 <name>Database Public API Spec</name>
11 <packaging>jar</packaging>
12
13 <profiles>
14 <profile>
15 <id>Rackspace Research Repositories</id>
16 <activation>
17 <activeByDefault>true</activeByDefault>
18 </activation>
19 <repositories>
20 <repository>
21 <id>rackspace-research</id>
22 <name>Rackspace Research Repository</name>
23 <url>http://maven.research.rackspacecloud.com/content/groups/public/</url>
24 </repository>
25 </repositories>
26 <pluginRepositories>
27 <pluginRepository>
28 <id>rackspace-research</id>
29 <name>Rackspace Research Repository</name>
30 <url>http://maven.research.rackspacecloud.com/content/groups/public/</url>
31 </pluginRepository>
32 </pluginRepositories>
33 </profile>
34 </profiles>
35 <properties>
36 <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
37 <doctools.version>1.5.0</doctools.version>
38 </properties>
39
40 <build>
41 <sourceDirectory>src</sourceDirectory>
42 <resources>
43 <resource>
44 <directory>../xsd</directory>
45 </resource>
46 </resources>
47 <plugins>
48 <plugin>
49 <groupId>com.rackspace.cloud.api</groupId>
50 <artifactId>clouddocs-maven-plugin</artifactId>
51 <!-- this <version> relates only to the *plugin* used for document formatting -->
52 <!-- the version of the *API* that is the subject of the document is indicated within each document -->
53 <version>${doctools.version}</version>
54 <executions>
55 <execution>
56 <id>g1</id>
57 <goals>
58 <goal>generate-pdf</goal>
59 <goal>generate-webhelp</goal>
60 </goals>
61 <phase>generate-sources</phase>
62 <configuration>
63 <xincludeSupported>true</xincludeSupported>
64 <sourceDirectory>src/resources</sourceDirectory>
65 <highlightSource>false</highlightSource>
66 <!-- this is the Rackspace-internal service developer guide formerly known as ManagementAPISpec.xml -->
67 <includes>cdb-mgmt-devguide.xml</includes>
68 <pdfUrl>../../cdb-mgmt-devguide-internal.pdf</pdfUrl>
69 <enableDisqus>intranet</enableDisqus>
70 <feedbackEmail>mike.asthalter@rackspace.com</feedbackEmail><postProcess>
71 <copy todir="target/docbkx/webhelp/cdb-mgmt-devguide/content/images">
72 <fileset dir="src/resources/images" includes="**/*.png"/>
73 </copy>
74 </postProcess>
75 </configuration>
76 </execution>
77 <execution>
78 <id>g2</id>
79 <goals>
80 <goal>generate-pdf</goal>
81 <goal>generate-webhelp</goal>
82 </goals>
83 <phase>generate-sources</phase>
84 <configuration>
85 <xincludeSupported>true</xincludeSupported>
86 <sourceDirectory>src/resources</sourceDirectory>
87 <highlightSource>false</highlightSource>
88 <trimWadlUriCount>2</trimWadlUriCount>
89 <!-- this is the public-facing client developer guide formerly known as PublicAPISpec.xml -->
90 <!-- this document that will be published as cdb-devguide-latest.pdf at http://docs.rackspacecloud.com/api/ -->
91 <pdfUrl>../../../cdb-devguide-latest.pdf</pdfUrl>
92 <enableDisqus>1</enableDisqus>
93 <googleAnalyticsId>UA-23102455-4</googleAnalyticsId>
94 <includes>cdb-devguide.xml</includes>
95 <canonicalUrlBase>http://docs.rackspace.com/cdb/api/v1.0/cdb-devguide/content</canonicalUrlBase>
96 <postProcess>
97 <copy todir="target/docbkx/webhelp/cdb-devguide/content/images">
98 <fileset dir="src/resources/images" includes="**/*.png"/>
99 </copy>
100 </postProcess>
101 </configuration>
102 </execution>
103 <execution>
104 <id>g3</id>
105 <goals>
106 <goal>generate-pdf</goal>
107 <goal>generate-webhelp</goal>
108 </goals>
109 <phase>generate-sources</phase>
110 <configuration>
111 <xincludeSupported>true</xincludeSupported>
112 <sourceDirectory>src/resources</sourceDirectory>
113 <highlightSource>false</highlightSource>
114 <!-- this is the Rackspace Getting Started guide -->
115 <includes>cdb-getting-started.xml</includes>
116 <pdfUrl>../../../cdb-getting-started.pdf</pdfUrl>
117 <enableDisqus>1</enableDisqus>
118 <googleAnalyticsId>UA-23102455-4</googleAnalyticsId>
119 <canonicalUrlBase>http://docs.rackspace.com/cdb/api/v1.0/cdb-getting-started/content</canonicalUrlBase>
120 <postProcess>
121 <copy todir="target/docbkx/webhelp/cdb-getting-started/content/images">
122 <fileset dir="src/resources/images" includes="**/*.png"/>
123 </copy>
124 </postProcess>
125 </configuration>
126 </execution>
127 <!-- MA: added this to generate public release notes -->
128 <execution>
129 <id>g4</id>
130 <goals>
131 <goal>generate-webhelp</goal>
132 <goal>generate-pdf</goal>
133 </goals>
134 <phase>generate-sources</phase>
135 <configuration>
136 <xincludeSupported>true</xincludeSupported>
137 <sourceDirectory>src/resources</sourceDirectory>
138 <highlightSource>false</highlightSource>
139 <pdfUrl>../../../cdb-releasenotes-latest.pdf</pdfUrl>
140 <includes>cdb-releasenotes.xml</includes>
141 <enableDisqus>1</enableDisqus>
142 <feedbackEmail>mike.asthalter@rackspace.com</feedbackEmail>
143 <enableGoogleAnalytics>1</enableGoogleAnalytics>
144 <chapterAutolabel>0</chapterAutolabel>
145 <security>external</security>
146 <canonicalUrlBase>http://docs.rackspace.com/cdb/api/v1.0/cdb-releasenotes/content</canonicalUrlBase>
147 <postProcess>
148 <move todir="target/docbkx/webhelp/cdb-releasenotes-external" failonerror="false">
149 <fileset dir="target/docbkx/webhelp/cdb-releasenotes"/>
150 </move>
151 <move file="target/docbkx/pdf/cdb-releasenotes.pdf" tofile="target/docbkx/pdf/cdb-releasenotes-YYYYMMDD.pdf" failonerror="false"/>
152 <delete file="target/docbkx/pdf/cdb-releasenotes.fo" failonerror="false"/>
153 </postProcess>
154 </configuration>
155 </execution>
156 <execution>
157 <id>g5</id>
158 <goals>
159 <goal>generate-pdf</goal>
160 <goal>generate-webhelp</goal>
161 </goals>
162 <phase>generate-sources</phase>
163 <configuration>
164 <xincludeSupported>true</xincludeSupported>
165 <sourceDirectory>src/resources</sourceDirectory>
166 <highlightSource>false</highlightSource>
167 <pdfUrl>../../../cdb-releasenotes-latest.pdf</pdfUrl>
168 <includes>cdb-releasenotes.xml</includes>
169 <enableDisqus>intranet</enableDisqus>
170 <feedbackEmail>mike.asthalter@rackspace.com</feedbackEmail>
171 <enableGoogleAnalytics>1</enableGoogleAnalytics>
172 <chapterAutolabel>0</chapterAutolabel>
173 <security>internal</security>
174 <canonicalUrlBase>http://docs-internal.rackspace.com/cdb/api/v1.0/cdb-releasenotes/content</canonicalUrlBase>
175 <postProcess>
176 <move todir="target/docbkx/webhelp/cdb-releasenotes-internal" failonerror="false">
177 <fileset dir="target/docbkx/webhelp/cdb-releasenotes"/>
178 </move>
179 <move file="target/docbkx/pdf/cdb-releasenotes.pdf" tofile="target/docbkx/pdf/cdb-releasenotes-internal.pdf" failonerror="false"/>
180 <delete file="target/docbkx/pdf/cdb-releasenotes.fo" failonerror="false"/>
181 </postProcess>
182 </configuration>
183 </execution>
184 </executions>
185 <configuration>
186 <socialIcons>1</socialIcons>
187 <feedbackEmail>mike.asthalter@rackspace.com</feedbackEmail>
188 <branding>rackspace</branding>
189 </configuration>
190 </plugin>
191 </plugins>
192 </build>
193</project>
diff --git a/integration/apidocs/src/resources/cdb-devguide.xml b/integration/apidocs/src/resources/cdb-devguide.xml
deleted file mode 100644
index 5c2ae69..0000000
--- a/integration/apidocs/src/resources/cdb-devguide.xml
+++ /dev/null
@@ -1,1675 +0,0 @@
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE book [
3 <!-- Some useful entities borrowed from HTML -->
4 <!ENTITY ndash "&#x2013;">
5 <!ENTITY mdash "&#x2014;">
6 <!ENTITY hellip "&#x2026;">
7
8 <!-- Useful for describing APIs -->
9 <!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
10 <!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
11 <!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
12 <!ENTITY DELETE '<command xmlns="http://docbook.org/ns/docbook">DELETE</command>'>
13
14 <!-- changing authentication endpoints; define entities for US & UK rather than maintaining in text -->
15 <!ENTITY ENDPOINT-US "https://identity.api.rackspacecloud.com/v1.1/">
16 <!ENTITY ENDPOINT-UK "https://lon.identity.api.rackspacecloud.com/v1.1/">
17 <!ENTITY ENDPOINT-US-20 "https://identity.api.rackspacecloud.com/v2.0/">
18 <!ENTITY ENDPOINT-UK-20 "https://lon.identity.api.rackspacecloud.com/v2.0/">
19
20 <!ENTITY CHECK '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
21 <imageobject>
22 <imagedata fileref="img/Check_mark_23x20_02.svg"
23 format="SVG" scale="60"/>
24 </imageobject>
25 </inlinemediaobject>'>
26
27 <!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
28 <imageobject>
29 <imagedata fileref="img/Arrow_east.svg"
30 format="SVG" scale="60"/>
31 </imageobject>
32 </inlinemediaobject>'>
33]>
34<book xmlns="http://docbook.org/ns/docbook"
35 xmlns:xlink="http://www.w3.org/1999/xlink"
36 xmlns:xi="http://www.w3.org/2001/XInclude"
37 xmlns:svg="http://www.w3.org/2000/svg"
38 xmlns:m="http://www.w3.org/1998/Math/MathML"
39 xmlns:html="http://www.w3.org/1999/xhtml"
40 xml:id="cdb-devguide"
41 version="5.0">
42
43 <?rax title.font.size="35px" subtitle.font.size="20px"?>
44 <title>Rackspace Cloud Databases Developer Guide</title>
45 <titleabbrev>Rackspace Cloud Databases Developer
46 Guide</titleabbrev>
47 <info>
48 <author>
49 <personname>
50 <firstname/>
51 <surname/>
52 </personname>
53 <affiliation>
54 <orgname>Rackspace Cloud</orgname>
55 </affiliation>
56 </author>
57 <copyright>
58 <year>2010</year>
59 <year>2011</year>
60 <year>2012</year>
61 <holder>Rackspace US, Inc.</holder>
62 </copyright>
63 <releaseinfo>API v1.0</releaseinfo>
64 <productname>Rackspace Cloud Databases</productname>
65 <pubdate>2012-09-04</pubdate>
66 <legalnotice role="rs-api">
67 <annotation>
68 <remark>Copyright details are filled in by the template.</remark>
69 </annotation>
70 </legalnotice>
71 <abstract>
72 <para>This document is intended for software developers
73 interested in developing applications using the
74 Rackspace Cloud Databases Application Programming
75 Interface (<abbrev>API</abbrev>). </para>
76 </abstract>
77
78 <revhistory>
79 <revision>
80 <date>2012-09-04</date>
81 <revdescription>
82 <itemizedlist spacing="compact">
83 <listitem>
84 <para>Added information for pricing and
85 service level (refer to <xref
86 linkend="Pricing_SLA-d1e1362"
87 />).</para>
88 </listitem>
89 <listitem>
90 <para>Updated maximum volume size for a
91 database instance (refer to <xref
92 linkend="Absolute_Limits-d1e1397"
93 />).</para>
94 </listitem>
95 </itemizedlist>
96 </revdescription>
97 </revision>
98 <revision>
99 <date>2012-08-21</date>
100 <revdescription>
101 <itemizedlist spacing="compact">
102 <listitem>
103 <para>Changed FAILED status for database
104 instance to ERROR instead (see <xref
105 linkend="database_instance_status"
106 />).</para>
107 </listitem>
108 <listitem>
109 <para>List reserved names that cannot be
110 used for creating databases (see <xref
111 linkend="POST_createDatabase__version___accountId__instances__instanceId__databases_"
112 />) and users (see <xref
113 linkend="POST_createUser__version___accountId__instances__instanceId__users_"
114 />).</para>
115 </listitem>
116 </itemizedlist>
117 </revdescription>
118 </revision>
119 <revision>
120 <date>2012-08-01</date>
121 <revdescription>
122 <itemizedlist spacing="compact">
123 <listitem>
124 <para>Initial Unlimited Availability (UA)
125 release for Rackspace Cloud
126 Databases.</para>
127 </listitem>
128 </itemizedlist>
129 </revdescription>
130 </revision>
131 </revhistory>
132
133 <cover>
134 <para>this is a placeholder for the front cover</para>
135 </cover>
136 <cover>
137 <para>this is a placeholder for the back cover</para>
138 </cover>
139 <raxm:metadata xmlns:raxm="http://docs.rackspace.com/api/metadata">
140 <raxm:product version="v1.0">cdb</raxm:product>
141 <raxm:priority>2</raxm:priority>
142 </raxm:metadata>
143 </info>
144 <chapter xml:id="overview">
145 <title>Overview</title>
146 <para>Rackspace Cloud Databases is an OpenStack-based MySQL
147 relational database service that allows Rackspace
148 customers to easily provision database instances of
149 varying virtual resource sizes without the need to
150 maintain and/or update MySQL. Interactions with Cloud
151 Databases occur programmatically via the Cloud Databases
152 API as described in this developer guide.</para>
153 <note>
154 <para>Rackspace recommends that Cloud Databases users back
155 up their data using <emphasis role="bold"
156 >mysqldump</emphasis> until backups are supported
157 in Cloud Databases.</para>
158 </note>
159 <para>The following figure shows an
160 overview of Cloud Databases Infrastructure: <informalfigure>
161 <mediaobject>
162 <imageobject role="fo">
163 <imagedata
164 fileref="images/Cloud_DB_Infographic-1.svg"
165 contentwidth="6in"/>
166 </imageobject>
167 <imageobject role="html">
168 <imagedata
169 fileref="images/Cloud_DB_Infographic-1.png"/>
170 </imageobject>
171 </mediaobject>
172 </informalfigure>
173 </para>
174 <remark>Writer: need to get architecture diagram for DBaaS.
175 Emailed Daniel 5/1/12.</remark>
176 <para security="writeronly">We welcome feedback, comments, and bug reports at <link
177 xlink:href="http://feedback.rackspacecloud.com"
178 >http://feedback.rackspacecloud.com</link>.</para>
179 <remark>Writer: check whether following statement should be
180 added back in for public (not private) beta: Issues and
181 bug reports can be directed to your support team via
182 ticket, chat, email, or phone.</remark>
183 <?hard-pagebreak?>
184 <section xml:id="Intended_Audience-d1e122">
185 <title>Intended Audience</title>
186 <para> This Guide is intended to assist software
187 developers who want to develop applications using the
188 Cloud Databases API. It assumes the reader has a
189 general understanding of databases and is familiar
190 with: </para>
191 <itemizedlist spacing="compact">
192 <listitem>
193 <para>ReSTful web services</para>
194 </listitem>
195 <listitem>
196 <para>HTTP/1.1 conventions</para>
197 </listitem>
198 <listitem>
199 <para>JSON and/or XML data serialization
200 formats</para>
201 </listitem>
202 <listitem>
203 <para>ATOM Syndication Format</para>
204 </listitem>
205 </itemizedlist>
206 </section>
207 <?hard-pagebreak?>
208 <section xml:id="Document_Change_History-d1e166">
209 <title>Document Change History</title>
210 <para>This version of the Developer Guide replaces and
211 obsoletes all previous versions. The most recent
212 changes are described in the table below:</para>
213 <?rax revhistory?>
214 </section>
215 <section xml:id="Additional_Resources-d1e532">
216 <title>Additional Resources</title>
217 <para>Descriptive information about Cloud Databases is
218 also published in its Web Application Description
219 Language (WADL) and XML Schema Definition (XSD). You
220 are welcome to read this information here:</para>
221 <itemizedlist>
222 <listitem>
223 <para>The WADL is <link
224 xlink:href="http://docs.rackspace.com/cdb/api/v1.0/cdb.wadl"
225 />.</para>
226 </listitem>
227 <listitem>
228 <para>The XSD is <link
229 xlink:href="http://docs.rackspace.com/cdb/api/v1.0/xsd/cdb.xsd"/>. </para>
230 </listitem>
231 </itemizedlist>
232 <para>You can download the most current versions of other
233 API-related documents from <link
234 xlink:href="http://docs.rackspace.com/"
235 >http://docs.rackspace.com/</link>. </para>
236 <para>For more details about Rackspace Cloud Databases,
237 refer to <link
238 xlink:href="http://www.rackspace.com/cloud/cloud_hosting_products/databases/"
239 >http://www.rackspace.com/cloud/cloud_hosting_products/databases/</link>.
240 This site also offers links to Rackspace's official
241 support channels, including knowledge center articles,
242 forums, phone, chat, and email. </para>
243 <para>Using this API document, your Rackspace Cloud
244 account, and at least one Cloud Server, you can get
245 started whenever you'd like. See the
246 <citetitle>Getting Started with Rackspace Cloud
247 Databases and Servers</citetitle> at <link
248 xlink:href="http://docs.rackspace.com/"
249 >http://docs.rackspace.com/</link> for information
250 about getting started using the API.</para>
251 <para>Please visit our <link
252 xlink:href="http://feedback.rackspacecloud.com/forums/71021-product-feedback/category/42449-cloud-databases"
253 >Product Feedback Forum</link> and let us know
254 what you think about Cloud Databases!</para>
255 <para>You can also follow Rackspace updates and
256 announcements via twitter at: <link
257 xlink:href="http://www.twitter.com/rackspace"
258 >http://www.twitter.com/rackspace</link>. </para>
259 <para>This API uses standard HTTP 1.1 response codes as
260 documented at: <link
261 xlink:href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html"
262 >http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html</link>. </para>
263 </section>
264 <?hard-pagebreak?>
265 <section xml:id="Pricing_SLA-d1e1362">
266 <title>Pricing and Service Level</title>
267 <para>Cloud Databases is part of the Rackspace Cloud and
268 your use through the API will be billed as per the
269 pricing schedule at <link
270 xlink:href="http://www.rackspace.com/cloud/public/databases/pricing"
271 >http://www.rackspace.com/cloud/public/databases/pricing</link>.</para>
272 <para>The Service Level Agreement (SLA) for Cloud
273 Databases is available at <link
274 xlink:href="http://www.rackspace.com/cloud/legal/sla/#cloud_databases"
275 >http://www.rackspace.com/cloud/legal/sla/#cloud_databases</link>.</para>
276 </section>
277 </chapter>
278
279 <chapter xml:id="Concepts-d1e563">
280 <title>Concepts</title>
281 <?dbhtml stop-chunking?>
282 <para> To use the Cloud Databases API effectively, you should
283 understand several key concepts: </para>
284 <remark>Reviewer: Daniel Morris is asking Daniel Salinas to
285 do an initial write-up of this chapter.</remark>
286 <section xml:id="DatabaseInstance-d1e588">
287 <title>Database Instance</title>
288 <para>A database instance is an isolated MySQL instance in
289 a single tenant environment on a shared physical host
290 machine.</para>
291 <remark security="writeronly">Writer: once we support
292 MSSQL, we need to describe here what is used for MSSQL
293 in place of database instance.</remark>
294 </section>
295 <section xml:id="Database">
296 <title>Database</title>
297 <para>A MySQL database within a database instance.</para>
298 <remark security="writeronly">Writer: once we support
299 MSSQL, we need to modify the wording here, such as:
300 The actual database, whether it is in MySQL or
301 MSSQL.</remark>
302 </section>
303 <section xml:id="Flavor">
304 <title>Flavor</title>
305 <para>A flavor is an available hardware configuration for
306 a database instance. Each flavor has a unique
307 combination of memory capacity and priority for CPU
308 time.</para>
309 </section>
310 <section xml:id="Volume">
311 <title>Volume</title>
312 <para>A volume is user-specified storage that contains the
313 MySQL data directory. Volumes are automatically
314 provisioned on shared Internet Small Computer System
315 Interface (iSCSI) storage area networks (SAN) that
316 provide for increased performance, scalability,
317 availability and manageability. Applications with high
318 I/O demands are performance optimized and data is
319 protected through both local and network RAID-10.
320 Additionally, network RAID provides synchronous
321 replication of volumes with automatic failover and
322 load balancing across available storage
323 clusters.</para>
324 </section>
325 </chapter>
326 <chapter xml:id="General_API_Information-d1e633">
327 <title>General API Information</title>
328 <para> The Cloud Databases API is implemented using a ReSTful
329 web service interface. Like other products in the
330 Rackspace Cloud suite, the Database Service shares a
331 common token-based authentication system that allows
332 seamless access between products and services. </para>
333 <note>
334 <para> All requests to authenticate against and operate the service are performed using
335 SSL over HTTP (HTTPS) on TCP port 443. </para>
336 </note>
337 <section xml:id="Authentication-d1e647">
338 <title>Authentication</title>
339 <para> Every ReST request against the Database Service
340 requires the inclusion of a specific authorization
341 token, supplied by the <code>X-Auth-Token</code> HTTP
342 header. Customers obtain this token by first using the
343 Rackspace Cloud Authentication Service and supplying a
344 valid username and API access key. </para>
345 <section xml:id="Geographic_Endpoints">
346 <title>Geographic Endpoints</title>
347 <para> The Rackspace Cloud Authentication Service
348 serves as the entry point to all Rackspace Cloud
349 APIs and is itself a ReSTful web service. </para>
350 <para> To access the Authentication Service, you must
351 know whether your account is US-based or UK-based: </para>
352 <itemizedlist spacing="compact">
353 <listitem>
354 <para> US-based accounts authenticate through
355 <link xlink:href="&ENDPOINT-US-20;"
356 >&ENDPOINT-US-20;</link>. </para>
357 </listitem>
358 <listitem>
359 <para> UK-based accounts authenticate through
360 <link xlink:href="&ENDPOINT-UK-20;"
361 >&ENDPOINT-UK-20;</link>. </para>
362 </listitem>
363 </itemizedlist>
364 <para> Your account may be based in either the US or
365 the UK; this is not determined by your physical
366 location but by the location of the Rackspace
367 retail site which was used to create your account: </para>
368 <itemizedlist spacing="compact">
369 <listitem>
370 <para> If your account was created via <link
371 xlink:href="http://www.rackspacecloud.com"
372 >http://www.rackspacecloud.com</link>,
373 it is a US-based account. </para>
374 </listitem>
375 <listitem>
376 <para> If your account was created via <link
377 xlink:href="http://www.rackspace.co.uk"
378 >http://www.rackspace.co.uk</link>, it
379 is a UK-based account. </para>
380 </listitem>
381 </itemizedlist>
382 <para> If you are unsure how your account was created,
383 use the Rackspace contact information at either
384 site to ask for help. </para>
385 </section>
386 <section xml:id="Retrieving_Auth_Token">
387 <title>Retrieving the Authentication Token</title>
388 <informaltable rules="all">
389 <tbody>
390 <tr>
391 <td colspan="1">&POST; </td>
392 <td colspan="1"> v2.0/tokens </td>
393 <td colspan="4"> Authenticate to receive a
394 token and a service catalog. </td>
395 </tr>
396 </tbody>
397 </informaltable>
398 <simpara> Normal Response Code(s):
399 <returnvalue>200</returnvalue>,
400 <returnvalue>203</returnvalue>
401 </simpara>
402 <simpara> Error Response Code(s): unauthorized
403 (<errorcode>401</errorcode>), userDisabled
404 (<errorcode>403</errorcode>), badRequest
405 (<errorcode>400</errorcode>), authFault
406 (<errorcode>500</errorcode>),
407 serviceUnavailable (<errorcode>503</errorcode>) </simpara>
408 <para> The authenticate operation provides clients
409 with an authentication token and a list of
410 regional cloud endpoints. The sample requests and
411 responses in this section illustrate a general
412 case. In your authentication request, use your own
413 credentials rather than the sample values shown
414 here for <code>username</code> and
415 <code>apiKey</code>. When you authenticate
416 successfully, the response to your authentication
417 request will include a catalog of the services to
418 which you have subscribed rather than the sample
419 values shown here.</para>
420 <example>
421 <title>Auth Request: XML</title>
422 <programlistingco>
423 <areaspec>
424 <area xml:id="credentials.xml.user"
425 units="linecolumn" coords="13 17"/>
426 <area xml:id="credentials.xml.key"
427 units="linecolumn" coords="14 15"/>
428 </areaspec>
429 <programlisting language="xml">
430<xi:include href="samples/db-credentials-20.xml" parse="text"/>
431 </programlisting>
432 </programlistingco>
433 </example>
434 <example>
435 <title>Auth Request: JSON</title>
436 <programlistingco>
437 <areaspec>
438 <area xml:id="credentials.json.user"
439 units="linecolumn" coords="14 22"/>
440 <area xml:id="credentials.json.key"
441 units="linecolumn" coords="15 20"/>
442 </areaspec>
443 <programlisting language="json">
444<xi:include href="samples/db-credentials-20.json" parse="text"/>
445 </programlisting>
446 </programlistingco>
447 </example>
448 <calloutlist>
449 <callout arearefs="credentials.xml.user">
450 <para> The username supplied here is your
451 common Rackspace Cloud username. </para>
452 </callout>
453 <callout arearefs="credentials.xml.key">
454 <para> The key is your API access key. The key
455 can be obtained from the Rackspace Cloud
456 Control Panel in the <guimenu>&lt;Your
457 Account></guimenu>/<guimenuitem>API
458 Access</guimenuitem> section (login
459 here: <link
460 xlink:href="http://mycloud.rackspace.com/"
461 >Control Panel Login</link>). </para>
462 </callout>
463 </calloutlist>
464 <example>
465 <title>Auth Response: XML</title>
466
467 <programlistingco>
468 <areaspec>
469 <area xml:id="response.xml.namespaces" units="linecolumn" coords="7 9"/>
470 <area xml:id="response.xml.token" units="linecolumn" coords="12 10"/>
471 <area xml:id="response.xml.role" units="linecolumn" coords="14 12"/>
472 <area xml:id="response.xml.catalog" units="linecolumn" coords="19 21"/>
473 <area xml:id="response.xml.servicetype" units="linecolumn" coords="43 34"/>
474 <area xml:id="response.xml.servicename" units="linecolumn" coords="43 54"/>
475 <area xml:id="response.xml.region" units="linecolumn" coords="44 30"/>
476 <area xml:id="response.xml.tenant" units="linecolumn" coords="45 66"/>
477 <area xml:id="response.xml.url" units="linecolumn" coords="46 9"/>
478 </areaspec>
479 <programlisting language="xml"><xi:include href="samples/db-auth-20.xml" parse="text"/></programlisting>
480 </programlistingco>
481 </example>
482
483
484 <example xml:id="auth-response-example-json">
485 <title>Auth Response: JSON</title>
486
487 <programlistingco>
488 <areaspec>
489 <area xml:id="response.json.namespaces" units="linecolumn" coords="200 1"/>
490 <area xml:id="response.json.token" units="linecolumn" coords="9 8"/>
491 <area xml:id="response.json.role" units="linecolumn" coords="16 12"/>
492 <area xml:id="response.json.catalog" units="linecolumn" coords="29 8"/>
493 <area xml:id="response.json.servicetype" units="linecolumn" coords="102 16"/>
494 <area xml:id="response.json.servicename" units="linecolumn" coords="101 16"/>
495 <area xml:id="response.json.region" units="linecolumn" coords="94 24"/>
496 <area xml:id="response.json.tenant" units="linecolumn" coords="91 24"/>
497 <area xml:id="response.json.url" units="linecolumn" coords="92 24"/>
498 </areaspec>
499 <programlisting language="json"><xi:include href="samples/db-auth-20.json" parse="text"/>
500 </programlisting>
501 </programlistingco>
502 </example>
503 <note>
504 <para>The information shown in the Auth Response
505 examples is for US-based accounts. If you
506 authenticate against the UK-endpoint for auth,
507 you will see the service catalog information
508 for UK-based accounts.</para>
509 </note>
510 <calloutlist>
511 <callout arearefs="response.xml.namespaces">
512 <para>
513 In XML responses only,
514 a list of namespaces identifies API extensions that add functionality to the core API.
515 </para>
516 <para> </para>
517 </callout>
518 <callout arearefs="response.xml.token">
519 <para> This token can be presented to a service as evidence of authentication.
520 Tokens are valid for a finite duration; a token's default lifespan is twenty-four hours.
521 </para>
522 <para> The token's <code>expires</code> attribute denotes the time
523 after which the token will automatically become
524 invalid. A token may be manually revoked before
525 the time identified by the <code>expires</code>
526 attribute; <code>expires</code> predicts a token's
527 maximum possible lifespan but does not guarantee
528 that it will reach that lifespan. Clients are
529 encouraged to cache a token until it expires. </para>
530 <para> </para>
531 </callout>
532 <callout arearefs="response.xml.role">
533 <para> Users can be assigned multiple roles,
534 with each role providing specific
535 privileges. In this example,
536 <code>jsmith</code> is the
537 administrative user for the account,
538 holding the fully-privileged
539 <code>identity:admin</code> role.
540 Other users might hold other roles with
541 different privileges. Roles need not be
542 associated with actual job functions such
543 as Administrator, Operator, Developer,
544 Tester, or Trainer. </para>
545 <para> </para>
546 </callout>
547 <callout arearefs="response.xml.catalog">
548 <para> The service catalog lists the services
549 this user can access. In this example, the
550 user can access one database service, one
551 loadbalancing service, two compute
552 services (Cloud Servers OpenStack and
553 Cloud Servers), two object storage
554 services (Cloud Files Content Distribution
555 Network (CDN), and Cloud Files), and one
556 DNS service. The catalog listing for each
557 service provides at least one endpoint URL
558 for that service. Other information, such
559 as regions, versions, and tenants, is
560 provided if it's relevant to this user's
561 access to this service. </para>
562 <para> </para>
563 </callout>
564 <callout arearefs="response.xml.servicetype">
565 <para>
566 The service type attribute identifies services that perform similar functions, whatever those services might be named.
567 In this example, the services named cloudServers and cloudServersOpenstack are both identified as <code>type="compute"</code>,
568 identifying them as compute services even though the word "compute" does not appear in their names.
569 </para>
570 <important>
571 <para>Use service type as the primary value for
572 locating a service. If multiple endpoints of the
573 same service type exist in the same region, use
574 service name as the tiebreaker.</para>
575 </important>
576 <para> </para>
577 </callout>
578 <callout arearefs="response.xml.servicename">
579 <para>
580 The service name attribute identifies each unique service in the catalog.
581 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.
582 </para>
583 <important>
584 <para> If you are programmatically parsing an authentication
585 response, use service type rather than service name as
586 the basis for determining whether a user has access to
587 a particular kind of service. Service type is stable
588 across all releases; new service types may be developed,
589 but existing service types are not renamed.
590 In this example,
591 <code>type="compute"</code> identifies all the
592 available compute services, one of which is named
593 cloudServers and one of which is named
594 cloudServersOpenStack. New compute service names may be added
595 in future releases; whatever the compute services are
596 named, you can always
597 recognize them by parsing for
598 <code>type="compute"</code> in the authentication
599 response's service catalog. </para>
600 </important>
601 <para> </para>
602 </callout>
603 <callout arearefs="response.xml.region">
604 <para> A service may expose endpoints in different regions.
605 Regional endpoints allow clients to provision
606 resources in a manner that provides high
607 availability. </para>
608 <para> Some services are not region-specific. These services supply a single
609 non-regional endpoint and do not provide access to internal URLs. </para>
610 <para> </para>
611 </callout>
612 <callout arearefs="response.xml.tenant">
613 <para> Some services recognize specification of a tenant. If a
614 service does recognize tenants, the format of the
615 tenant specification is defined only by the
616 service; for details about whether and how to
617 specify a tenant, check the documentation for the
618 service you are using.</para>
619 <para> </para>
620 </callout>
621 <callout arearefs="response.xml.url">
622 <para>
623 An endpoint can be assigned public and internal URLs. A
624 public URL is accessible from anywhere. Access to a public
625 URL usually incurs traffic charges. Internal URLs are only
626 accessible to services within the same region. Access to
627 an internal URL is free of charge.
628 </para>
629 <para> </para>
630 </callout>
631 </calloutlist>
632 <para>Authentication tokens are typically valid for 24
633 hours. Applications should be designed to
634 re-authenticate after receiving a 401
635 (Unauthorized) response from a service endpoint. </para>
636 <important>
637 <para>If you are programmatically parsing an
638 authentication response, please be aware that
639 service names are stable for the life of the
640 particular service and can be used as keys.
641 You should also be aware that a user's service
642 catalog can include multiple uniquely-named
643 services which perform similar functions. For
644 example, cloudServersOpenStack is the
645 OpenStack version of compute whereas
646 cloudServers is the legacy version of compute;
647 the same user can have access to both
648 services. In Auth 2.0, the service type
649 attribute can be used as a key by which to
650 recognize similar services; see the tip
651 below.</para>
652 </important>
653 <tip>
654 <para>Beginning with Auth 2.0, the service catalog
655 includes a service type attribute to identify
656 services that perform similar functions but
657 have different names; for example,
658 <code>type="compute"</code> identifies
659 compute services such as cloudServers and
660 cloudServersOpenStack. Some developers have
661 found the service type attribute to be useful
662 in parsing the service catalog. For additional
663 information on Auth 2.0 (also known as the
664 Cloud Identity Service), refer to the
665 <citetitle>Cloud Identity Client Developer
666 Guide</citetitle> at <link
667 xlink:href="http://docs.rackspace.com"
668 >http://docs.rackspace.com/</link>.</para>
669 </tip>
670 <para>Databases service endpoints are published in the
671 service catalog in the Auth response with the
672 account number, which is a required element of the
673 service endpoints. The examples shown here are for
674 authentication for US customers. Customers with
675 UK-based accounts will see different values in the
676 service catalog. Refer to the next section for
677 more information about service endpoints. </para>
678 </section>
679 </section>
680 <section xml:id="Service_Access_Endpoints-d1e753">
681 <title>Service Access/Endpoints</title>
682 <para>The Database Service is a regionalized service. The
683 user of the service is therefore responsible for
684 appropriate replication, caching, and overall
685 maintenance of Cloud Databases data across regional
686 boundaries to other Cloud Databases servers.</para>
687 <para>You can find the available service access/endpoints
688 for Cloud Databases summarized in the table
689 below.</para>
690 <?rax-fo keep-with-next?>
691 <para>
692 <table rules="all">
693 <caption>Regionalized Service Endpoints</caption>
694 <thead>
695 <tr align="center">
696 <td colspan="2">Region</td>
697 <td colspan="5">Endpoint</td>
698 </tr>
699 </thead>
700 <tbody>
701 <tr align="left">
702 <td colspan="2">Chicago (ORD)</td>
703 <td colspan="5"
704 ><code>https://ord.databases.api.rackspacecloud.com/v1.0/</code><parameter>1234</parameter>/ </td>
705 </tr>
706 <tr align="left">
707 <td colspan="2">Dallas/Ft. Worth (DFW)</td>
708 <td colspan="5"
709 ><code>https://dfw.databases.api.rackspacecloud.com/v1.0/</code><parameter>1234</parameter>/ </td>
710 </tr>
711 <tr align="left" >
712 <td colspan="2">London (LON)</td>
713 <td colspan="5">
714 <code>https://lon.databases.api.rackspacecloud.com/v1.0/</code><parameter>1234</parameter>/ </td>
715 </tr>
716 </tbody>
717 </table>
718 </para>
719
720 <para>Replace the sample account ID number,
721 <parameter>1234</parameter>, with your actual
722 account number returned as part of the authentication
723 service response.</para>
724 <para>You will find the actual account number after the
725 final '/' in the <code>publicURL</code> field returned
726 by the authentication response. For example, in <xref
727 linkend="auth-response-example-json"/> you can see
728 from the <code>publicURL</code> field for
729 <code>cloudServers</code>
730 ("https://servers.api.rackspacecloud.com/v1.0/<emphasis
731 role="bold">1100111</emphasis>") that the account
732 number is 1100111.</para>
733 </section>
734 <section xml:id="DB_service_versions">
735 <title>Cloud Databases Service Versions</title>
736 <para> The Cloud Databases version defines the contract
737 and build information for the API. </para>
738 <section xml:id="Contract_Version-d1e825">
739 <title>Contract Version</title>
740 <para> The contract version denotes the data model and
741 behavior that the API supports. The requested
742 contract version is included in all request URLs.
743 Different contract versions of the API may be
744 available at any given time and are not guaranteed
745 to be compatible with one another.
746 </para>
747 <example>
748 <title>Example Request URL (contract version
749 in <emphasis role="strong"
750 >bold</emphasis>)</title>
751 <programlisting>https://ord.databases.api.rackspacecloud.com/<emphasis role="strong">v1.0</emphasis>/1234</programlisting>
752 </example>
753 <note>
754 <para>This document pertains to contract
755 version 1.0.</para>
756 </note>
757
758 </section>
759 <section xml:id="API_Version_Headers-d1e855">
760 <title>API Version</title>
761 <para>The API List Versions call is available to show
762 the current API version as well as information
763 about all versions of the API. Refer to <xref
764 linkend="API_Versions"/> for details.</para>
765 </section>
766 </section>
767 <section xml:id="Request_Response_Types-d1e903">
768 <title>Request/Response Types</title>
769 <para> The Cloud Databases API supports both the JSON and
770 XML data serialization formats. The request format is
771 specified using the <code>Content-Type</code> header
772 and is <emphasis>required</emphasis> for calls that
773 have a request body. The response format can be
774 specified in requests either by using the
775 <code>Accept</code> header or by adding an
776 <code>.xml</code> or <code>.json</code> extension
777 to the request URI. Note that it is possible for a
778 response to be serialized using a format different
779 from the request. If no response format is specified,
780 JSON is the default. If conflicting formats are
781 specified using both an <code>Accept</code> header and
782 a query extension, the query extension takes
783 precedence.</para>
784 <para security="writeronly">Some operations support an Atom representation that
785 can be used to efficiently determine when the state of
786 services has changed. </para>
787 <remark>Reviewer: the previous sentence will be hidden
788 for the Private Beta, since it does not appear that
789 Atom will be supported yet. Correct?</remark>
790 <table rules="all">
791 <caption>Response Formats</caption>
792 <?dbfo keep-together="always"?>
793 <thead>
794 <tr align="center">
795 <td>Format</td>
796 <td>Accept Header</td>
797 <td>Query Extension</td>
798 <td>Default</td>
799 </tr>
800 </thead>
801 <tbody>
802 <tr>
803 <td>JSON</td>
804 <td>application/json</td>
805 <td>.json</td>
806 <td>Yes</td>
807 </tr>
808 <tr>
809 <td>XML</td>
810 <td>application/xml</td>
811 <td>.xml</td>
812 <td>No</td>
813 </tr>
814 <tr security="writeronly">
815 <td>ATOM</td>
816 <td>application/atom+xml</td>
817 <td>.atom</td>
818 <td>No</td>
819 </tr>
820 </tbody>
821 </table>
822 <remark>Reviewer: the ATOM row in the table above will be
823 hidden for the Private Beta, since it does not appear
824 that Atom will be supported yet. Correct?</remark>
825 <para>In the request example below, notice that
826 <parameter>Content-Type</parameter> is set to
827 <parameter>application/json</parameter>, but
828 <parameter>application/xml</parameter> is
829 requested via the <parameter>Accept</parameter>
830 header:</para>
831 <example xml:id="request_with_headers_json">
832 <title>Request with Headers: JSON</title>
833 <?dbfo keep-together="always"?>
834 <programlisting language="json"><xi:include href="samples/db-request-types.json" parse="text"><xi:fallback>Missing code sample!<?rax fail?></xi:fallback></xi:include></programlisting>
835 </example>
836 <para><?rax-fo keep-with-next?>Therefore an XML response format is returned:</para>
837 <example>
838 <title>Response with Headers: XML</title>
839 <?dbfo keep-together="always"?>
840 <programlisting language="xml"><xi:include href="samples/db-response-types.xml" parse="text"><xi:fallback>Missing code sample!<?rax fail?></xi:fallback></xi:include></programlisting>
841 </example>
842 </section>
843 <section xml:id="sync_asynch_responses" security="writeronly">
844 <title>Synchronous and Asynchronous Responses</title>
845 <remark>Reviewer: please give me the updated info for this
846 section. Need to replace info about callback URL,
847 etc.</remark>
848 <para> All successful &GET; requests are
849 <emphasis>synchronous</emphasis> calls, since they
850 are always retrieving (reading) existing information.
851 With these requests, the caller waits until the call
852 returns with the specified code and response body. For
853 an example, see XXXX.</para>
854 <para>&PUT;, &POST;, and &DELETE; calls are <emphasis>asynchronous</emphasis>, however,
855 since they may take some time to process. Therefore they return 202 ACCEPTED
856 responses containing information with a callback URL, which allows the progress,
857 status, and/or response information of the call to be retrieved at a later point in
858 time. The asynchronous response body will look similar to the following examples,
859 depending on the format requested:</para>
860 <example>
861 <title>202 ACCEPTED Response: XML</title>
862 <?dbfo keep-together="always"?>
863 <programlisting language="xml">Reviewer: need code example</programlisting>
864 </example>
865 <example>
866 <title>202 ACCEPTED Response: JSON</title>
867 <?dbfo keep-together="always"?>
868 <programlisting language="json">Reviewer: need code example</programlisting>
869 </example>
870 <para>The following table shows the attributes for asynchronous responses:</para>
871 <table rules="all">
872 <caption>Attributes for Asynchronous Responses</caption>
873 <?dbfo keep-together="always"?>
874 <thead>
875 <tr align="center">
876 <td colspan="1">Attribute</td>
877 <td colspan="4">Description</td>
878 </tr>
879 </thead>
880 <tbody>
881 <tr>
882 <td colspan="1">jobId</td>
883 <td colspan="4">An identifier for the specific request.</td>
884 </tr>
885 <tr>
886 <td colspan="1">callbackUrl</td>
887 <td colspan="4">Resource locator for querying the status of the request.</td>
888 </tr>
889 </tbody>
890 </table>
891 <note>
892 <para>The status for asynchronous calls is retained for up to 24 hours.</para>
893 </note>
894 <note>
895 <para>If a request body does not pass initial validation or an error condition
896 arises, you may receive an immediate error response from the request.</para>
897 </note>
898 <para>When a request is made to the callback URL provided
899 and the job is still running, another
900 <returnvalue>202</returnvalue> ACCEPTED response
901 is returned with the same information as the previous
902 one. If the request is complete, the response will be
903 as if the original call returned as normal, without
904 waiting. For example, if a Create Database request was
905 issued and a 202 asynchronous response was returned,
906 the response from querying the callback URL for a
907 completed successful database creation would be a
908 <returnvalue>200</returnvalue> OK and contain the
909 information for the created database. See XXXX for a
910 specific example.</para>
911 <para>If an error occurs during the processing of the
912 create request, querying the callback URL will return
913 the details of the error, as if the original call
914 returned the error response. For example, if a
915 validation error occurs during the Create Database
916 request above, the response from querying the callback
917 URL would be a <returnvalue>400</returnvalue> BAD
918 REQUEST and contain details regarding the specific
919 validation error.</para>
920 <note>
921 <para>If the response from querying a callback URL is a
922 <returnvalue>404</returnvalue> NOT FOUND, the details of the error in the
923 response body will contain information the caller may use to determine whether
924 the specified job itself was not found, or if the response from the original
925 request was a <returnvalue>404</returnvalue> NOT FOUND. </para>
926 </note>
927 <para>The description of each &PUT;, &POST;, and &DELETE;
928 request identifies the response codes that can
929 indicate success or error for that request. For
930 example, see XXXX immediately below the table for a
931 list of the successful and error response codes for
932 the POST /xxxx call.</para>
933 </section>
934 <section xml:id="Content_Compression-d1e1120" security="writeronly">
935 <title>Content Compression</title>
936 <remark>Reviewer: I am hiding this entire section for the
937 Private Beta, since I'm not sure that it applies. Is
938 that correct?</remark>
939 <para> Request and response body data may be encoded with gzip compression to accelerate
940 interactive performance of API calls and responses. This is controlled using the
941 <code>Accept-Encoding</code> header on the request from the client and indicated
942 by the <code>Content-Encoding</code> header in the server response. Unless the
943 header is explicitly set, encoding defaults to disabled. </para>
944 <table rules="all">
945 <caption>Encoding Headers</caption>
946 <?dbfo keep-together="always"?>
947 <thead>
948 <tr align="center">
949 <td>Header Type</td>
950 <td>Name</td>
951 <td>Value</td>
952 </tr>
953 </thead>
954 <tbody>
955 <tr>
956 <td>HTTP/1.1 Request</td>
957 <td><code>Accept-Encoding</code></td>
958 <td>gzip</td>
959 </tr>
960 <tr>
961 <td>HTTP/1.1 Response</td>
962 <td><code>Content-Encoding</code></td>
963 <td>gzip</td>
964 </tr>
965 </tbody>
966 </table>
967 </section>
968 <section xml:id="Persistent_Connections-d1e1187" security="writeronly">
969 <title>Persistent Connections</title>
970 <remark>Reviewer: I am hiding this entire section for the
971 Private Beta, since I'm not sure that it applies. Is
972 that correct?</remark>
973 <para>
974 By default, the API supports persistent connections
975 via HTTP/1.1 keepalives. All connections will be kept
976 alive unless the connection header is set to close.
977 </para>
978 <para>
979 To prevent abuse, HTTP sessions have a timeout of 20
980 seconds before being closed.
981 </para>
982 <note>
983 <para>
984 The server may close the connection at any time
985 and clients should not rely on this behavior.
986 </para>
987 </note>
988 </section>
989 <?hard-pagebreak?>
990 <section xml:id="Limits-d1e1208">
991 <title>Limits</title>
992 <para>
993 All accounts, by default, have a preconfigured set of
994 thresholds (or limits) to manage capacity and prevent
995 abuse of the system. The system recognizes two kinds
996 of limits: <firstterm>rate limits</firstterm> and
997 <firstterm>absolute limits</firstterm>. Rate limits
998 are thresholds that are reset after a certain amount
999 of time passes. Absolute limits are fixed.
1000 </para>
1001 <section xml:id="Rate_Limits-d1e1222">
1002 <title>Rate Limits</title>
1003 <para> Rate limits are specified in terms of both a
1004 human-readable wild-card URI and a
1005 machine-processable regular expression. The
1006 regular expression boundary matcher '^' takes
1007 effect after the root URI path. For example, the
1008 regular expression ^/v1.0/instances would match
1009 the bolded portion of the following URI:
1010 https://ord.databases.api.rackspacecloud.com<emphasis
1011 role="bold">/v1.0/instances</emphasis>. </para>
1012 <para>The following table specifies the default rate
1013 limits for all API operations for all &GET;,
1014 &POST;, &PUT;, and &DELETE; calls for databases
1015 and database instances: </para>
1016 <table rules="all">
1017 <caption>Default Rate Limits</caption>
1018 <thead>
1019 <tr align="center">
1020 <td colspan="1">Verb</td>
1021 <td colspan="2">URI</td>
1022 <td colspan="2">RegEx</td>
1023 <td colspan="1">Default</td>
1024 </tr>
1025 </thead>
1026 <tbody>
1027 <tr>
1028 <td colspan="1">&GET; changes-since</td>
1029 <td colspan="2">*/instances/*</td>
1030 <td colspan="2">^/vd+.d+/instances.*</td>
1031 <td colspan="1">3/minute</td>
1032 </tr>
1033 <tr>
1034 <td colspan="1">&POST;</td>
1035 <td colspan="2">*/instances/*</td>
1036 <td colspan="2">^/vd+.d+/instances.*</td>
1037 <td colspan="1">10/minute</td>
1038 </tr>
1039 <tr>
1040 <td colspan="1">&POST; instances</td>
1041 <td colspan="2">*/instances/*</td>
1042 <td colspan="2">^/vd+.d+/instances.*</td>
1043 <td colspan="1">50/day</td>
1044 </tr>
1045 <tr>
1046 <td colspan="1">&PUT;</td>
1047 <td colspan="2">*/instances/*</td>
1048 <td colspan="2">^/vd+.d+/instances.*</td>
1049 <td colspan="1">10/minute</td>
1050 </tr>
1051 <tr>
1052 <td colspan="1">&DELETE;</td>
1053 <td colspan="2">*/instances/*</td>
1054 <td colspan="2">^/vd+.d+/instances.*</td>
1055 <td colspan="1">100/minute</td>
1056 </tr>
1057 </tbody>
1058 </table>
1059 <para> Rate limits are applied in order relative to the
1060 verb, going from least to most specific. For
1061 example, although the threshold for &POST; to
1062 /v1.0/* is 10 per minute, one cannot &POST; to
1063 /v1.0/* more than 50 times within a single day. </para>
1064 <para> If you exceed the thresholds established for
1065 your account, a <errorcode>413 (Rate
1066 Control)</errorcode> HTTP response will be
1067 returned with a <code>Retry-After</code> header to
1068 notify the client when it can attempt to try
1069 again. </para>
1070 </section>
1071 <section xml:id="Absolute_Limits-d1e1397">
1072 <title>Absolute Limits</title>
1073 <remark>Reviewer: Need to update this entire section.
1074 Please give me your updates.</remark>
1075 <para>Refer to the following table for the absolute
1076 limits that are set.</para>
1077 <table rules="all">
1078 <caption>Absolute Limits</caption>
1079 <thead>
1080 <tr>
1081 <td colspan="1">Name</td>
1082 <td colspan="3">Description</td>
1083 <td colspan="1">Limit</td>
1084 </tr>
1085 </thead>
1086 <tbody>
1087 <tr>
1088 <td colspan="1">Instances</td>
1089 <td colspan="3">Maximum number of instances allowed
1090 for your account</td>
1091 <td colspan="1">5</td>
1092 </tr>
1093 <tr>
1094 <td colspan="1">Volume Size</td>
1095 <td colspan="3">Maximum volume size per
1096 instance in gigabytes (GB) for your
1097 account</td>
1098 <td colspan="1">50</td>
1099 </tr>
1100 </tbody>
1101 </table>
1102 </section>
1103 </section>
1104 <section xml:id="datetimeformat">
1105 <title>Date/Time Format</title>
1106 <para> The Database Service uses an ISO-8601 compliant
1107 date format for the display and consumption of
1108 date/time values. </para>
1109 <para>The system timezone is in UTC. MySQL converts TIMESTAMP values from
1110 the current time zone to UTC for storage, and back
1111 from UTC to the current time zone for retrieval.
1112 This does not occur for other types, such as DATETIME.
1113 </para>
1114 <example>
1115 <title>DB Service Date/Time Format</title>
1116 <programlisting>yyyy-MM-dd'T'HH:mm:ss.SSSZ</programlisting>
1117 <para>See the table below for a description of the date/time format codes.</para>
1118 <para>May 19th, 2011 at 8:07:08 AM, GMT-5 would have the following
1119 format:</para>
1120 <programlisting>2011-05-19T08:07:08-05:00</programlisting>
1121 </example>
1122 <table rules="all">
1123 <caption>Explanation of Date/Time Format Codes</caption>
1124 <thead>
1125 <tr>
1126 <td>Code</td>
1127 <td>Description</td>
1128 </tr>
1129 </thead>
1130 <tbody>
1131 <tr>
1132 <td>yyyy</td>
1133 <td>Four digit year</td>
1134 </tr>
1135 <tr>
1136 <td>MM</td>
1137 <td>Two digit month</td>
1138 </tr>
1139 <tr>
1140 <td>dd</td>
1141 <td>Two digit day of month</td>
1142 </tr>
1143 <tr>
1144 <td>T</td>
1145 <td>Separator for date/time</td>
1146 </tr>
1147 <tr>
1148 <td>HH</td>
1149 <td>Two digit hour of day (00-23)</td>
1150 </tr>
1151 <tr>
1152 <td>mm</td>
1153 <td>Two digit minutes of hour</td>
1154 </tr>
1155 <tr>
1156 <td>ss</td>
1157 <td>Two digit seconds of the minute</td>
1158 </tr>
1159 <tr>
1160 <td>SSS</td>
1161 <td>Three digit milliseconds of the second</td>
1162 </tr>
1163 <tr>
1164 <td>Z</td>
1165 <td>RFC-822 timezone</td>
1166 </tr>
1167 </tbody>
1168 </table>
1169
1170 </section>
1171 <section xml:id="pagination">
1172 <title>Pagination</title>
1173 <para>To reduce load on the service, list operations
1174 return a maximum of 20 items at a time. This is
1175 referred to as <emphasis>pagination</emphasis>. Cloud
1176 Databases has separate paging limits for instances,
1177 databases, and users, which are currently all set to
1178 20. If a request supplies no limit or one that exceeds
1179 the configured default limit, the default is used
1180 instead.</para>
1181 <para> Pagination provides the ability to limit the size
1182 of the returned data as well as retrieve a specified
1183 subset of a large data set. Pagination has two key
1184 concepts: limit and marker. <emphasis>Limit</emphasis>
1185 is the restriction on the maximum number of items for
1186 that type that can be returned.
1187 <emphasis>Marker</emphasis> is the ID of the last
1188 item in the previous list returned. The ID is the UUID
1189 in the case of instances, and the name in the case of
1190 databases and users. For example, a query could
1191 request the next 10 instances after the instance
1192 "1234" as follows:
1193 <code>?limit=10&amp;marker=1234</code>. Items are
1194 displayed sorted by ID. </para>
1195 <para>Pagination applies only to the calls listed in the
1196 following table: </para>
1197 <informaltable rules="all">
1198 <thead>
1199 <tr align="center">
1200 <td colspan="1">Verb</td>
1201 <td colspan="2">URI</td>
1202 <td colspan="3">Description</td>
1203 </tr>
1204 </thead>
1205 <tbody>
1206 <tr>
1207 <td colspan="1">&GET;</td>
1208 <td colspan="2">/instances/</td>
1209 <td colspan="3">Lists the status and
1210 information for all database
1211 instances.</td>
1212 </tr>
1213 <tr>
1214 <td colspan="1">&GET;</td>
1215 <td colspan="2">
1216 /instances/{instanceId}/databases </td>
1217 <td colspan="3">Lists databases for the
1218 specified instance.</td>
1219 </tr>
1220 <tr>
1221 <td colspan="1">&GET;</td>
1222 <td colspan="2"> /instances/{instanceId}/users </td>
1223 <td colspan="3">Lists the users in the
1224 specified database instance.</td>
1225 </tr>
1226 </tbody>
1227 </informaltable>
1228 <para>If the content returned by a call is paginated, the
1229 response includes a structured link much like an
1230 instance item's links, with the basic structure
1231 <code>{"href": "&lt;url>", "rel": "next"}</code>.
1232 Any response that is truncated by pagination will have
1233 a <emphasis>next</emphasis> link, which points to the
1234 next item in the collection. If there are no more
1235 items, no <emphasis>next</emphasis> link is
1236 returned.</para>
1237 <para>See the examples of paged List Instances calls that
1238 follow.</para>
1239 <example>
1240 <title>List Instances Paged Request: XML</title>
1241 <?dbfo keep-together="always"?>
1242 <programlisting language="xml">
1243<xi:include href="samples/db-instances-index-pagination-request.xml" parse="text"/>
1244 </programlisting>
1245 </example>
1246 <example>
1247 <title>List Instances Paged Request: JSON</title>
1248 <?dbfo keep-together="always"?>
1249 <programlisting language="json">
1250<xi:include href="samples/db-instances-index-pagination-request.json" parse="text"/>
1251 </programlisting>
1252 </example>
1253 <para>Notice that the paged request examples above set the
1254 limit to 2 (<code>?limit=2</code>), so the responses
1255 that follow each show 2 instances and return a
1256 <emphasis>marker</emphasis> set to the UUID of the
1257 last item in the returned list
1258 (<code>?marker=4137d6a4-03b7-4b66-b0ef-8c7c35c470d3</code>).
1259 Also a link is provided to retrieve the next 2 results
1260 (<code>limit=2</code>) in the link element
1261 identified by the attribute <code>rel="next"</code>
1262 (XML) or <code>"rel":"next"</code> (JSON):</para>
1263 <example>
1264 <title>List Instances Paged Response: XML</title>
1265 <?dbfo keep-together="always"?>
1266 <programlisting language="xml">
1267<xi:include href="samples/db-instances-index-pagination-response.xml" parse="text"/>
1268 </programlisting>
1269 </example>
1270 <example>
1271 <title>List Instances Paged Response: JSON</title>
1272 <?dbfo keep-together="always"?>
1273 <programlisting language="json">
1274<xi:include href="samples/db-instances-index-pagination-response.json" parse="text"/>
1275 </programlisting>
1276 </example>
1277 </section>
1278 <section xml:id="efficient_polling_changes_since_parm" security="writeronly">
1279 <title>Efficient Polling with the
1280 <parameter>Changes-Since</parameter>
1281 Parameter</title>
1282 <remark>Reviewer: I have hidden this section, since it
1283 does not appear that it will be supported for Private
1284 Beta. Correct?</remark>
1285 <para> The ReST API allows you to poll for the status of
1286 certain operations by performing a &GET; on various
1287 URIs. Rather than re-downloading and re-parsing the
1288 full status at each polling interval, your ReST client
1289 may use the <parameter>changes-since</parameter>
1290 parameter to check for changes since a previous
1291 request. The <parameter>changes-since</parameter> time
1292 is specified as <link
1293 xlink:href="http://en.wikipedia.org/wiki/Unix_time"
1294 >Unix time</link> (the number of seconds since
1295 January 1, 1970, 00:00:00 UTC, not counting leap
1296 seconds). If nothing has changed since the
1297 <parameter>changes-since</parameter> time, a
1298 <returnvalue>304 (Not Modified)</returnvalue>
1299 response will be returned. If data has changed, only
1300 the items changed since the specified time will be
1301 returned in the response. </para>
1302 <remark>Reviewer: does the following sentence apply, and
1303 should it be included?</remark>
1304 <para>For example, performing a &GET; against
1305 https://api.servers.rackspacecloud.com/v1.0/224532/servers?<parameter>changes-since</parameter>=1244012982
1306 would list all servers that have changed since Wed, 03
1307 Jun 2009 07:09:42 UTC. </para>
1308 </section>
1309 <section xml:id="DB_faults">
1310 <title>Faults</title>
1311 <para> When an error occurs, the Database Service returns
1312 a fault object containing an HTTP error response code
1313 that denotes the type of error. In the body of the
1314 response, the system will return additional
1315 information about the fault. </para>
1316 <para>The following table lists possible fault types with their associated error codes
1317 and descriptions.</para>
1318 <informaltable rules="all">
1319 <thead>
1320 <tr align="center">
1321 <td colspan="2">Fault Type</td>
1322 <td colspan="1">Associated Error Code</td>
1323 <td colspan="3">Description</td>
1324 </tr>
1325 </thead>
1326 <tbody>
1327 <tr>
1328 <td colspan="2"><code>badRequest</code></td>
1329 <td colspan="1">400</td>
1330 <td colspan="3">There was one or more errors in the user request.</td>
1331 </tr>
1332 <tr>
1333 <td colspan="2"><code>unauthorized</code></td>
1334 <td colspan="1">401</td>
1335 <td colspan="3">The supplied token is not authorized to access the resources, either it's expired or invalid.</td>
1336 </tr>
1337 <tr>
1338 <td colspan="2"><code>forbidden</code></td>
1339 <td colspan="1">403</td>
1340 <td colspan="3">Access to the requested
1341 resource was denied.</td>
1342 </tr>
1343 <tr>
1344 <td colspan="2"><code>itemNotFound</code></td>
1345 <td colspan="1">404</td>
1346 <td colspan="3">The back-end services did not
1347 find anything matching the
1348 Request-URI.</td>
1349 </tr>
1350 <tr>
1351 <td colspan="2"><code>badMethod</code></td>
1352 <td colspan="1">405</td>
1353 <td colspan="3">The request method is not allowed for this resource.</td>
1354 </tr>
1355 <tr>
1356 <td colspan="2"><code>overLimit</code></td>
1357 <td colspan="1">413</td>
1358 <td colspan="3">Either the number of entities in the request is larger than
1359 allowed limits, or the user has exceeded allowable request rate limits.
1360 See the <code>details</code> element for more specifics. Contact support
1361 if you think you need higher request rate limits.</td>
1362 </tr>
1363 <tr>
1364 <td colspan="2"><code>badMediaType</code></td>
1365 <td colspan="1">415</td>
1366 <td colspan="3">The requested content type is not supported by this service.</td>
1367 </tr>
1368 <tr>
1369 <td colspan="2"
1370 ><code>unprocessableEntity</code></td>
1371 <td colspan="1">422</td>
1372 <td colspan="3">The requested resource could
1373 not be processed on at the moment.</td>
1374 </tr>
1375 <tr>
1376 <td colspan="2"
1377 ><code>instanceFault</code></td>
1378 <td colspan="1">500</td>
1379 <td colspan="3">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.</td>
1380 </tr>
1381 <tr>
1382 <td colspan="2"
1383 ><code>notImplemented</code></td>
1384 <td colspan="1">501</td>
1385 <td colspan="3">The requested method or resource is not implemented.</td>
1386 </tr>
1387 <tr>
1388 <td colspan="2"
1389 ><code>serviceUnavailable</code></td>
1390 <td colspan="1">503</td>
1391 <td colspan="3">The Database Service is not
1392 available.</td>
1393 </tr>
1394 </tbody>
1395 </informaltable>
1396 <para>The following two <code>instanceFault</code>
1397 examples show errors when the server has erred or
1398 cannot perform the requested operation:</para>
1399
1400 <example>
1401 <title>Example instanceFault Response: XML</title>
1402 <?dbfo keep-together="always"?>
1403 <programlisting language="xml">
1404<xi:include href="samples/db-faults-instanceFault.xml" parse="text"/>
1405 </programlisting>
1406 </example>
1407 <example>
1408 <title>Example Fault Response: JSON</title>
1409 <?dbfo keep-together="always"?>
1410 <programlisting language="json">
1411<xi:include href="samples/db-faults-instanceFault.json" parse="text"/>
1412 </programlisting>
1413 </example>
1414 <para> The error code (<code>code</code>) is returned in the body of the response for
1415 convenience. The <code>message</code> element returns a human-readable message that
1416 is appropriate for display to the end user. The <code>details</code> element is
1417 optional and may contain information that is useful for tracking down an error, such
1418 as a stack trace. The <code>details</code> element may or may not be appropriate for
1419 display to an end user, depending on the role and experience of the end user.</para>
1420 <para>The fault's root element (for example,
1421 <code>instanceFault</code>) may change depending
1422 on the type of error. </para>
1423 <para><?rax-fo keep-with-next?>The following two <code>badRequest</code> examples
1424 show errors when the volume size is invalid:</para>
1425 <example>
1426 <title>Example badRequest Fault on Volume Size Errors:
1427 XML</title>
1428 <?dbfo keep-together="always"?>
1429 <programlisting language="xml">
1430<xi:include href="samples/db-faults-badRequest.xml" parse="text"/>
1431 </programlisting>
1432 </example>
1433 <example>
1434 <title>Example badRequest Fault on Volume Size Errors:
1435 JSON</title>
1436 <?dbfo keep-together="always"?>
1437 <programlisting language="json">
1438<xi:include href="samples/db-faults-badRequest.json" parse="text"/>
1439 </programlisting>
1440 </example>
1441 <para> The next two examples show
1442 <code>itemNotFound</code> errors:</para>
1443 <example>
1444 <title>Example itemNotFound Fault: XML</title>
1445 <?dbfo keep-together="always"?>
1446 <programlisting language="xml">
1447<xi:include href="samples/db-faults-itemNotFound.xml" parse="text"/>
1448 </programlisting>
1449 </example>
1450 <example>
1451 <title>Example itemNotFound Fault: JSON</title>
1452 <?dbfo keep-together="always"?>
1453 <programlisting language="json">
1454<xi:include href="samples/db-faults-itemNotFound.json" parse="text"/>
1455 </programlisting>
1456 </example>
1457 </section>
1458 <section xml:id="database_instance_status">
1459 <title>Database Instance Status</title>
1460 <para><?rax-fo keep-with-next?>When making an API call to create, list, or delete
1461 database instance(s), the following database instance
1462 status values are possible:</para>
1463 <itemizedlist spacing="compact">
1464 <listitem>
1465 <para>BUILD &ndash; The database instance is being provisioned.</para>
1466 </listitem>
1467 <listitem>
1468 <para>REBOOT &ndash; The database instance is
1469 rebooting.</para>
1470 </listitem>
1471 <listitem>
1472 <para>ACTIVE &ndash; The database instance is
1473 online and available to take requests.</para>
1474 </listitem>
1475 <listitem>
1476 <para>BLOCKED &ndash; The database instance is
1477 unresponsive at the moment.</para>
1478 </listitem>
1479 <listitem>
1480 <para>RESIZE &ndash; The database instance is being
1481 resized at the moment.</para>
1482 </listitem>
1483 <listitem>
1484 <para>SHUTDOWN &ndash; The database instance is
1485 terminating services. Also, SHUTDOWN is
1486 returned if for any reason the MySQL instance
1487 is shut down but not the actual server. </para>
1488 <para>
1489 <note>
1490 <para>If MySQL has crashed (causing the
1491 SHUTDOWN status), please call support
1492 for assistance.</para>
1493 </note>
1494 </para>
1495 </listitem>
1496 <listitem>
1497 <para>ERROR &ndash; The last operation for the
1498 database instance failed due to an
1499 error.</para>
1500 </listitem>
1501 </itemizedlist>
1502 </section>
1503 <section xml:id="Accessibility">
1504 <title>Database Instance Accessibility</title>
1505 <para>Database instances are directly accessible only on
1506 the internal ServiceNet network and using a Cloud
1507 resource within the same regional datacenter. For
1508 example, a database instance in DFW can only be
1509 accessed by a Cloud Server in DFW.</para>
1510 <para>Note that using a public Cloud Load Balancer allows
1511 you to access your ServiceNet database instance from
1512 the public network by performing the following steps:<orderedlist>
1513 <listitem>
1514 <para>Using the Cloud Databases API, create a
1515 database instance. For details see <xref
1516 linkend="POST_createInstance__version___accountId__instances_"
1517 />.</para>
1518 </listitem>
1519 <listitem>
1520 <para>Using the Cloud Load Balancers API,
1521 create a public load balancer and specify
1522 your database instance hostname as a node,
1523 or use the API to add your instance
1524 hostname as a node to an existing public
1525 load balancer. For details refer to the
1526 <citetitle>Cloud Load Balancers
1527 Developer Guide</citetitle> at <link
1528 xlink:href="http://docs.rackspace.com/api/"
1529 >http://docs.rackspace.com/api/</link>.</para>
1530 </listitem>
1531 </orderedlist></para>
1532 </section>
1533 </chapter>
1534
1535 <chapter xml:id="API_Operations-d1e2264"
1536 xmlns="http://docbook.org/ns/docbook"
1537 role="api-reference">
1538 <title>API Operations</title>
1539 <note>
1540 <para>Do not use trailing slashes (/) at the end of calls
1541 to API operations, since this may cause the call to
1542 fail. For example, do not use &GET; /instances/detail/
1543 (with the trailing slash at the end). Rather, use
1544 &GET; /instances/detail instead.</para>
1545 </note>
1546 <?hard-pagebreak?>
1547 <section xml:id="API_Versions">
1548 <title>API Versions</title>
1549 <para>This section describes the versions that are
1550 supported for the Cloud Databases API.</para>
1551 <wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
1552 <wadl:resource href="../../../xsd/dbaas.wadl#versions">
1553 <wadl:method href="getVersions"/>
1554 </wadl:resource>
1555 <wadl:resource href="../../../xsd/dbaas.wadl#version">
1556 <wadl:method href="getVersionInfo" />
1557 </wadl:resource>
1558 </wadl:resources>
1559
1560 </section>
1561
1562 <section xml:id="Database_Instances">
1563 <title>Database Instances</title>
1564 <para>This section describes the operations that are supported for database instances.</para>
1565 <wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
1566 <wadl:resource href="../../../xsd/dbaas.wadl#instances" >
1567 <wadl:method href="createInstance"/>
1568 <wadl:method href="getInstance"/>
1569 </wadl:resource>
1570
1571 <wadl:resource href="../../../xsd/dbaas.wadl#instanceId">
1572 <wadl:method href="getInstanceById"/>
1573 <wadl:method href="deleteInstance"/>
1574 </wadl:resource>
1575 <wadl:resource href="../../../xsd/dbaas.wadl#root">
1576 <wadl:method href="createRoot"/>
1577 <wadl:method href="isRootEnabled"/>
1578 </wadl:resource>
1579 </wadl:resources>
1580 </section>
1581
1582 <section xml:id="Database_Instances_Actions">
1583 <title>Database Instance Actions</title>
1584 <para>This section describes the actions that are supported for database instances.</para>
1585 <wadl:resources xmlns:wadl="http://wadl.dev.java.net/2009/02">
1586 <wadl:resource href="../../../xsd/dbaas.wadl#instanceAction" >
1587 <wadl:method href="restartInstance"/>
1588 <wadl:method href="resizeInstance"/>
1589 <wadl:method href="resizeVolume"/>
1590 </wadl:resource>
1591 </wadl:resources>
1592 </section>
1593
1594 <section xml:id="databases">
1595 <title>Databases</title>
1596 <para>This section describes the operations that are
1597 supported for databases.</para>
1598 <wadl:resources
1599 xmlns:wadl="http://wadl.dev.java.net/2009/02">
1600 <wadl:resource href="../../../xsd/dbaas.wadl#databases">
1601 <wadl:method href="createDatabase"/>
1602 <wadl:method href="getDatabases"/>
1603 </wadl:resource>
1604 <wadl:resource href="../../../xsd/dbaas.wadl#databaseName">
1605 <wadl:method href="deleteDatabase"/>
1606 </wadl:resource>
1607 </wadl:resources>
1608 </section>
1609
1610 <section xml:id="user_management">
1611 <title>Users</title>
1612 <para>This section describes the operations that are
1613 supported for managing database users.</para>
1614 <wadl:resources
1615 xmlns:wadl="http://wadl.dev.java.net/2009/02">
1616 <wadl:resource href="../../../xsd/dbaas.wadl#users">
1617 <wadl:method href="createUser"/>
1618 <wadl:method href="getUsers"/>
1619 </wadl:resource>
1620 <wadl:resource href="../../../xsd/dbaas.wadl#userId">
1621 <wadl:method href="deleteUser"/>
1622 </wadl:resource>
1623 </wadl:resources>
1624 </section>
1625
1626 <section xml:id="flavors">
1627 <title>Flavors</title>
1628 <para>This section describes the operations that are
1629 supported for flavors.</para>
1630 <wadl:resources
1631 xmlns:wadl="http://wadl.dev.java.net/2009/02">
1632 <wadl:resource href="../../../xsd/dbaas.wadl#flavors">
1633 <wadl:method href="getFlavors"/>
1634 </wadl:resource>
1635
1636 <wadl:resource href="../../../xsd/dbaas.wadl#flavorId">
1637 <wadl:method href="getFlavorById"/>
1638 </wadl:resource>
1639 </wadl:resources>
1640 </section>
1641 </chapter>
1642 <glossary>
1643 <title>Glossary</title>
1644 <glossentry xml:id="Database-d1e017">
1645 <glossterm>database</glossterm>
1646 <glossdef>
1647 <para>A MySQL database within a database instance.</para>
1648 </glossdef>
1649 </glossentry>
1650 <glossentry xml:id="Database-Instance-d1e016">
1651 <glossterm>database instance</glossterm>
1652 <glossdef>
1653 <para>A database instance is an isolated MySQL instance in a single tenant environment on a
1654 shared physical host machine. Also referred to as instance.</para>
1655 </glossdef>
1656 </glossentry>
1657 <glossentry xml:id="Flavor-d1e018">
1658 <glossterm>flavor</glossterm>
1659 <glossdef>
1660 <para>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.</para>
1661 </glossdef>
1662 </glossentry>
1663 <glossentry xml:id="Volume-d1e019">
1664 <glossterm>volume</glossterm>
1665 <glossdef>
1666 <para>A volume is user-specified storage that contains the MySQL data directory.
1667 Volumes are automatically provisioned on shared Internet Small Computer System Interface (iSCSI)
1668 storage area networks (SAN) that provide for increased performance, scalability, availability
1669 and manageability. Applications with high I/O demands are performance optimized and data is
1670 protected through both local and network RAID-10. Additionally, network RAID provides synchronous
1671 replication of volumes with automatic failover and load balancing across available storage clusters.</para>
1672 </glossdef>
1673 </glossentry>
1674 </glossary>
1675</book>
diff --git a/integration/apidocs/src/resources/cdb-getting-started.xml b/integration/apidocs/src/resources/cdb-getting-started.xml
deleted file mode 100644
index ba3275b..0000000
--- a/integration/apidocs/src/resources/cdb-getting-started.xml
+++ /dev/null
@@ -1,1131 +0,0 @@
1<?xml version="1.0" encoding="UTF-8"?>
2
3<!DOCTYPE book [
4 <!-- Some useful entities borrowed from HTML -->
5 <!ENTITY ndash "&#x2013;">
6 <!ENTITY mdash "&#x2014;">
7 <!ENTITY hellip "&#x2026;">
8
9 <!-- Useful for describing APIs -->
10 <!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
11 <!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
12 <!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
13 <!ENTITY DELETE '<command xmlns="http://docbook.org/ns/docbook">DELETE</command>'>
14
15 <!-- changing authentication endpoints; define entities for US & UK rather than maintaining in text -->
16 <!ENTITY ENDPOINT-US "https://identity.api.rackspacecloud.com/v1.1/">
17 <!ENTITY ENDPOINT-UK "https://lon.identity.api.rackspacecloud.com/v1.1/">
18 <!ENTITY ENDPOINT-US-20 "https://identity.api.rackspacecloud.com/v2.0/">
19 <!ENTITY ENDPOINT-UK-20 "https://lon.identity.api.rackspacecloud.com/v2.0/">
20
21 <!-- Useful for specs -->
22 <!ENTITY MAY '<emphasis xmlns="http://docbook.org/ns/docbook" role="strong">MAY</emphasis>'>
23 <!ENTITY SHOULD '<emphasis xmlns="http://docbook.org/ns/docbook" role="strong">SHOULD</emphasis>'>
24 <!ENTITY MUST '<emphasis xmlns="http://docbook.org/ns/docbook" role="strong">MUST</emphasis>'>
25 <!ENTITY MUST_NOT '<emphasis xmlns="http://docbook.org/ns/docbook" role="strong">MUST NOT</emphasis>'>
26]>
27
28<book version="5.0"
29 xmlns="http://docbook.org/ns/docbook"
30 xmlns:xlink="http://www.w3.org/1999/xlink"
31 xmlns:xi="http://www.w3.org/2001/XInclude"
32 xmlns:svg="http://www.w3.org/2000/svg"
33 xmlns:m="http://www.w3.org/1998/Math/MathML"
34 xmlns:html="http://www.w3.org/1999/xhtml"
35 xml:id="cdb-getting-started">
36
37 <?rax title.font.size="35px" subtitle.font.size="20px"?>
38 <title>Rackspace Cloud Databases Getting Started Guide</title>
39 <titleabbrev>Rackspace Cloud Databases and Servers Getting Started Guide</titleabbrev>
40
41 <info>
42
43 <copyright>
44 <year>2011</year>
45 <year>2012</year>
46 <holder>Rackspace US, Inc.</holder>
47 </copyright>
48 <releaseinfo>API v1.0</releaseinfo>
49 <productname>Rackspace Cloud Databases</productname>
50 <pubdate>2012-09-04</pubdate>
51 <legalnotice role="rs-api">
52 <annotation>
53 <remark>Copyright details are filled in by the template.</remark>
54 </annotation>
55 </legalnotice>
56 <revhistory>
57 <revision>
58 <date>2012-09-04</date>
59 <revdescription>
60 <itemizedlist spacing="compact">
61 <listitem>
62 <para>Added information for pricing and
63 service level (refer to <xref
64 linkend="Pricing_SLA-d1e1362"
65 />).</para>
66 </listitem>
67 </itemizedlist>
68 </revdescription>
69 </revision>
70 <revision>
71 <date>2012-08-02</date>
72 <revdescription>
73 <itemizedlist spacing="compact">
74 <listitem>
75 <para>Corrected request examples for
76 authentication (refer to <xref
77 linkend="Generating_Auth_Token"
78 />).</para>
79 </listitem>
80 </itemizedlist>
81 </revdescription>
82 </revision>
83 <revision>
84 <date>2012-08-01</date>
85 <revdescription>
86 <itemizedlist spacing="compact">
87 <listitem>
88 <para>Initial Unlimited Availability (UA)
89 release for Rackspace Cloud
90 Databases.</para>
91 </listitem>
92 </itemizedlist>
93 </revdescription>
94 </revision>
95 </revhistory>
96 <raxm:metadata xmlns:raxm="http://docs.rackspace.com/api/metadata">
97 <raxm:product version="v1.0">cdb</raxm:product>
98 <raxm:priority>1</raxm:priority>
99 </raxm:metadata>
100 </info>
101 <chapter xml:id="DB_Doc_Change_History">
102 <title>Document Change History</title>
103 <para>This version of the Getting Started replaces and
104 obsoletes all previous versions. The most recent changes
105 are described in the table below:</para>
106 <?rax revhistory?>
107 </chapter>
108 <chapter xml:id="DB_Overview">
109 <title>Overview</title>
110 <para>Follow the steps described in this guide to use the
111 Rackspace Cloud Databases API and the Cloud
112 Servers<trademark/> section of the Rackspace Cloud Control
113 Panel to create and access your database instances via
114 Rackspace Cloud Servers.</para>
115 <para>For details about using the Cloud Databases API, refer
116 to the <citetitle>Cloud Databases Developer
117 Guide</citetitle> at <link
118 xlink:href="http://docs.rackspace.com/"
119 >http://docs.rackspace.com/</link>.</para>
120 <para>For more details about Rackspace Cloud Databases, refer
121 to <link
122 xlink:href="http://www.rackspace.com/cloud/cloud_hosting_products/databases/"
123 >http://www.rackspace.com/cloud/cloud_hosting_products/databases/</link>.
124 This site also offers links to Rackspace's official
125 support channels, including knowledge center articles,
126 forums, phone, chat, and email. </para>
127 <para>Please visit our <link
128 xlink:href="http://feedback.rackspacecloud.com/forums/71021-product-feedback/category/42449-cloud-databases"
129 >Product Feedback Forum</link> and let us know what
130 you think about Cloud Databases!</para>
131 <section xml:id="Prerequisites_Examples">
132 <title>Prerequisites for Running Examples</title>
133 <para>In order to run the examples in this guide, you must
134 have the following prerequisites: <itemizedlist
135 spacing="compact">
136 <listitem>
137 <para>Rackspace Cloud account</para>
138 </listitem>
139 <listitem>
140 <para>Rackspace Cloud username and password,
141 as specified during registration</para>
142 </listitem>
143 </itemizedlist></para>
144 </section>
145 <section xml:id="Pricing_SLA-d1e1362">
146 <title>Pricing and Service Level</title>
147 <para>Cloud Databases is part of the Rackspace Cloud and
148 your use through the API will be billed as per the
149 pricing schedule at <link
150 xlink:href="http://www.rackspace.com/cloud/public/databases/pricing"
151 >http://www.rackspace.com/cloud/public/databases/pricing</link>.
152 Cloud Servers is also part of the Rackspace Cloud and
153 your use through the Control Panel will be billed as
154 per the pricing schedule at <link
155 xlink:href="http://www.rackspace.com/cloud/public/servers/pricing"
156 >http://www.rackspace.com/cloud/public/servers/pricing</link>.</para>
157 <para>The Service Level Agreements (SLAs) for Cloud
158 Databases and Cloud Servers are available at <link
159 xlink:href="http://www.rackspace.com/cloud/legal/sla/#cloud_databases"
160 >http://www.rackspace.com/cloud/legal/sla/#cloud_databases</link>
161 and <link
162 xlink:href="http://www.rackspace.com/cloud/legal/sla"
163 >http://www.rackspace.com/cloud/legal/sla</link>
164 respectively.</para>
165 </section>
166 </chapter>
167 <chapter xml:id="DB_Sending_API_Requests">
168 <title>Send Requests to the API</title>
169 <para>You have several options for sending requests through an
170 API: </para>
171 <itemizedlist spacing="compact">
172 <listitem>
173 <para>Developers and testers may prefer to use cURL,
174 the command-line tool from <link
175 xlink:href="http://curl.haxx.se/"
176 >http://curl.haxx.se/</link>. </para>
177 <para>With cURL you can send HTTP requests and receive
178 responses back from the command line. </para>
179 </listitem>
180 <listitem>
181 <para>If you like to use a more graphical interface,
182 the ReST client for Firefox also works well for
183 testing and trying out commands, see <link
184 xlink:href="https://addons.mozilla.org/en-US/firefox/addon/restclient/"
185 >https://addons.mozilla.org/en-US/firefox/addon/restclient/</link>. </para>
186 </listitem>
187 <listitem>
188 <para>You can also download and install rest-client, a
189 Java application to test ReSTful web services,
190 from <link
191 xlink:href="http://code.google.com/p/rest-client/"
192 >http://code.google.com/p/rest-client/</link>. </para>
193 </listitem>
194 </itemizedlist>
195 <section xml:id="DB_using-curl-cli">
196 <title>Send API Requests Using cURL</title>
197 <para>cURL is a command-line tool that is available on
198 most UNIX®-like environments and Mac OS X® and can be
199 downloaded for Windows® in order to interact with the
200 ReST interfaces. For more information on cURL, visit
201 <link xlink:href="http://curl.haxx.se/"
202 >http://curl.haxx.se/</link>. </para>
203 <para>cURL allows you to transmit and receive HTTP requests and responses from the
204 command-line or from within a shell script. This makes it possible to work with the ReST API
205 directly without using one of the client APIs. </para>
206 <para>The following cURL command-line options will be used
207 in this guide to run the examples:</para>
208 <variablelist>
209 <title>cURL Command-Line Options</title>
210 <varlistentry>
211 <term><option>-d</option></term>
212 <listitem>
213 <para>Sends the specified data in a post
214 request to the HTTP server.</para>
215 </listitem>
216 </varlistentry>
217 <varlistentry>
218 <term><option>-i</option></term>
219 <listitem>
220 <para>Includes the HTTP header in the
221 output.</para>
222 </listitem>
223 </varlistentry>
224 <varlistentry>
225 <term><option>-H HEADER</option></term>
226 <listitem>
227 <para>Specify an HTTP header in the request.</para>
228 </listitem>
229 </varlistentry>
230 </variablelist>
231 <note>
232 <para>If you have the tools, you can run the cURL JSON
233 request examples with the following options to
234 format the output from cURL: <command>&lt;curl
235 JSON request example> | python
236 -mjson.tool</command>.</para>
237 </note>
238 </section>
239 <section xml:id="DB_copy_paste_examples">
240 <title>Copying and Pasting cURL Request Examples into a
241 Terminal Window</title>
242 <para>To run the cURL request examples shown in this guide
243 on Linux or Mac systems, copy and paste each example
244 from the HTML version of this guide into an ASCII
245 editor (for example <emphasis role="bold"
246 >vi</emphasis> or <emphasis role="bold"
247 >TextEdit</emphasis>). Then modify each example
248 with your required account information and so forth,
249 as detailed in this guide.</para>
250 <note>
251 <para>The carriage returns in the cURL request
252 examples that are part of the cURL syntax are
253 escaped with a backslash ('\') in order to avoid
254 prematurely terminating the command. However you
255 should not escape carriage returns inside the xml
256 or json message within the command.</para>
257 </note>
258 <para>Consider the following cURL Authenticate Request:
259 XML example that is described in detail in <xref
260 linkend="Generating_Auth_Token"/>:</para>
261 <example>
262 <title>cURL Authenticate Request: XML</title>
263 <?dbfo keep-together="always"?>
264 <screen language="bash"><command>curl</command> <option>-i</option> <option>-d</option> \
265'&lt;?xml version="1.0" encoding="UTF-8"?>
266 &lt;auth&gt;   
267 &lt;apiKeyCredentials     
268 xmlns="http://docs.rackspace.com/identity/api/ext/RAX-KSKEY/v1.0"     
269 username="<emphasis role="bold">your_username</emphasis>"     
270 apiKey="<emphasis role="bold">your_api_key</emphasis>"/&gt;   
271 &lt;/auth&gt;<option>'</option> \
272<uri>'https://identity.api.rackspacecloud.com/v2.0/tokens'</uri></screen>
273 </example>
274 <para>You can see that the lines that are part of the cURL
275 command syntax have all been escaped with a backslash
276 ('\') to indicate that the command continues on the
277 next line:</para>
278 <screen language="bash"><command>curl</command> <option>-i</option> <option>-d</option> \
279
280   
281(... lines within the xml portion of the message are not shown in this example)
282(... the example only shows lines that are part of cURL syntax)     
283     
284    
285   
286 &lt;/auth&gt;<option>'</option> \
287<uri>'https://identity.api.rackspacecloud.com/v2.0/tokens'</uri></screen>
288 <para>However the lines <emphasis>within</emphasis> the
289 xml portion of the message are
290 <emphasis>not</emphasis> escaped with a backslash
291 ('\') in order to avoid issues with the xml
292 processing:</para>
293 <screen language="bash">'&lt;?xml version="1.0" encoding="UTF-8"?>
294 &lt;auth&gt;   
295 &lt;apiKeyCredentials     
296 xmlns="http://docs.rackspace.com/identity/api/ext/RAX-KSKEY/v1.0"     
297 username="<emphasis role="bold">your_username</emphasis>"     
298 apiKey="<emphasis role="bold">your_api_key</emphasis>"/&gt;   
299 &lt;/auth&gt;<option>'</option> \
300</screen>
301 <note>
302 <para>The final line of the xml message is escaped
303 since the backslash lies
304 <emphasis>outside</emphasis> the xml message
305 and continues the cURL command to the next
306 line.</para>
307 </note>
308 <para>After you are finished modifying the text for the
309 cURL request example with your information (for
310 example <emphasis role="bold"
311 ><code>your_username</code></emphasis> and
312 <emphasis role="bold"
313 ><code>your_api_key</code></emphasis>), paste it
314 into your terminal window. Then execute the cURL
315 command by pressing <guilabel>Enter</guilabel>.</para>
316 <para>If you have trouble copying and pasting the examples
317 as described, try typing the entire example on one
318 long line, removing all the backslash line
319 continuation characters.</para>
320 </section>
321 </chapter>
322 <chapter xml:id="Generating_Auth_Token">
323 <title>Generate an Authentication Token</title>
324 <para>You need to generate a token whether you use cURL or a
325 ReST client.</para>
326 <para>In order to use the ReST API, you will first need to
327 obtain an authentication token, which will need to be
328 passed in for each request using the
329 <code>X-Auth-Token</code> header. </para>
330 <para>The following example demonstrates how to use cURL to
331 obtain the authentication token and the account number.
332 You will need to supply the authentication token and
333 account number when making subsequent Cloud Databases API
334 calls.</para>
335 <para>Remember to replace the names in the Authenticate
336 Request examples below with their respective
337 values:<itemizedlist spacing="compact">
338 <listitem>
339 <para><emphasis role="bold"
340 >your_username</emphasis> &mdash; The
341 username is your common Rackspace Cloud
342 username, as supplied during
343 registration.</para>
344 </listitem>
345 <listitem>
346 <para><emphasis role="bold"
347 >your_api_key</emphasis> &mdash; The key
348 is your API access key. The key can be
349 obtained from the Rackspace Cloud Control
350 Panel in the <guimenu>&lt;Your
351 Account></guimenu> / <guimenuitem>API
352 Keys</guimenuitem> section (login here:
353 <link
354 xlink:href="http://mycloud.rackspace.com/"
355 >Control Panel Login</link>).</para>
356 </listitem>
357 </itemizedlist></para>
358 <para> To access the Authentication Service, you must know
359 whether your account is US-based or UK-based: </para>
360 <itemizedlist spacing="compact">
361 <listitem>
362 <para> US-based accounts authenticate through <link
363 xlink:href="&ENDPOINT-US-20;"
364 >&ENDPOINT-US-20;</link>. </para>
365 </listitem>
366 <listitem>
367 <para> UK-based accounts authenticate through <link
368 xlink:href="&ENDPOINT-UK-20;"
369 >&ENDPOINT-UK-20;</link>. </para>
370 </listitem>
371 </itemizedlist>
372 <para> Your account may be based in either the US or the UK;
373 this is not determined by your physical location but by
374 the location of the Rackspace retail site which was used
375 to create your account: </para>
376 <itemizedlist spacing="compact">
377 <listitem>
378 <para> If your account was created via <link
379 xlink:href="http://www.rackspacecloud.com"
380 >http://www.rackspacecloud.com</link>, it is a
381 US-based account. </para>
382 </listitem>
383 <listitem>
384 <para> If your account was created via <link
385 xlink:href="http:/www.rackspace.co.uk"
386 >http:/www.rackspace.co.uk</link>, it is a
387 UK-based account. </para>
388 </listitem>
389 </itemizedlist>
390 <para> If you are unsure how your account was created, use the
391 Rackspace contact information at either site to ask for
392 help. </para>
393 <para>Notice that you authenticate using a special URL for
394 Cloud authentication services. For example, for US-based
395 accounts, you use
396 <code>https://identity.api.rackspacecloud.com/v2.0/tokens</code>,
397 as shown in the following Authenticate Request examples.
398 Note that the <code>v2.0</code> component in the URL
399 indicates that you are using version 2.0 of the Cloud Auth
400 API.</para>
401 <example>
402 <title>cURL Authenticate Request: XML</title>
403 <?dbfo keep-together="always"?>
404 <screen language="bash"><command>curl</command> <option>-i</option> <option>-d</option> \
405'&lt;?xml version="1.0" encoding="UTF-8"?>
406&lt;auth>
407 &lt;apiKeyCredentials
408 xmlns="http://docs.rackspace.com/identity/api/ext/RAX-KSKEY/v1.0"
409 username="<emphasis role="bold">your_username</emphasis>"
410 apiKey="<emphasis role="bold">your_api_key</emphasis>"/>
411&lt;/auth>' \
412<option>-H 'Content-Type: application/xml'</option> \
413<option>-H 'Accept: application/xml'</option> \
414<uri>'https://identity.api.rackspacecloud.com/v2.0/tokens'</uri></screen>
415 </example>
416 <example>
417 <title>cURL Authenticate Request: JSON</title>
418 <?dbfo keep-together="always"?>
419 <screen language="bash"><command>curl</command> <option>-i</option> <option>-d</option> \
420'{
421 "auth":
422 {
423 "RAX-KSKEY:apiKeyCredentials":
424 {
425 "username": "<emphasis role="bold">your_username</emphasis>",
426 "apiKey": "<emphasis role="bold">your_api_key</emphasis>"}
427 }
428}' \
429<option>-H 'Content-Type: application/json'</option> \
430<uri>'https://identity.api.rackspacecloud.com/v2.0/tokens'</uri></screen>
431 </example>
432 <note>
433 <para>For UK-based accounts, you would need to modify the
434 URL shown in the last line of each of the Authenticate
435 Request examples above to be
436 <code>'https://lon.identity.api.rackspacecloud.com/v2.0/tokens'</code>
437 instead.</para>
438 </note>
439 <example>
440 <title>Authenticate Response: XML</title>
441 <programlisting language="xml"><xi:include href="../../src/resources/samples/db-auth-20.xml" parse="text"><xi:fallback>Missing code sample! <?rax fail?></xi:fallback></xi:include></programlisting>
442 </example>
443 <example>
444 <title>Authenticate Response: JSON</title>
445 <programlisting language="json"><xi:include href="../../src/resources/samples/db-auth-20.json" parse="text"><xi:fallback>Missing code sample! <?rax fail?></xi:fallback></xi:include></programlisting>
446 </example>
447 <para>The authentication token <code>id</code> is returned
448 along with an <code>expires</code> attribute that
449 specifies when the token expires. </para>
450 <note>
451 <title>Notes</title>
452 <itemizedlist spacing="compact">
453 <listitem>
454 <para>For all response examples in this guide, the
455 field values you receive in your responses
456 will vary from those shown here since they
457 will be specific to your account.</para>
458 </listitem>
459 <listitem>
460 <para>The information shown in the Authenticate
461 Response examples above is for US-based
462 accounts. If you authenticate against the
463 UK-endpoint for auth, you will see the service
464 catalog information for UK-based
465 accounts.</para>
466 </listitem>
467 <listitem>
468 <para>The <code>id</code> attribute in the
469 Authenticate Response specifies the
470 authentication token. Tokens are valid for a
471 finite duration.</para>
472 <para>Remember to supply your authentication token
473 wherever you see the field <emphasis
474 role="bold">your_auth_token</emphasis> in
475 the examples in this guide.</para>
476 </listitem>
477 <listitem>
478 <para> The <code>expires</code> attribute denotes
479 the time after which the token will
480 automatically become invalid. A token may be
481 manually revoked before the time identified by
482 the expires attribute; <code>expires</code>
483 predicts a token's maximum possible lifespan
484 but does not guarantee that it will reach that
485 lifespan. Clients are encouraged to cache a
486 token until it expires.</para>
487 </listitem>
488 <listitem>
489 <para>Applications should be designed to
490 re-authenticate after receiving a 401
491 (Unauthorized) response from a service
492 endpoint.</para>
493 </listitem>
494 </itemizedlist>
495 </note>
496 <para>The <code>publicURL</code> endpoints for
497 <code>cloudDatabases</code> (for example
498 <code>https://ord.databases.api.rackspacecloud.com/v1.0/1100111</code>)
499 are also returned in the response. </para>
500 <para>You will find the actual account number after the final
501 '/' in the <code>publicURL</code> field. In this example,
502 you can see that the account number is 1100111. You need
503 to specify your account number on most of the Cloud
504 Databases API calls, wherever you see the field <emphasis
505 role="bold">your_acct_id</emphasis> specified in the
506 examples in this guide.</para>
507 <para>After authentication, you can use cURL to perform &GET;,
508 &DELETE;, and &POST; requests for the Cloud Databases
509 API.</para>
510 </chapter>
511 <chapter xml:id="Service_Access_Endpoints-d1e753">
512 <title>Service Access/Endpoints</title>
513 <para>The endpoints to use for your Cloud Databases API calls
514 are summarized in the table below.</para>
515
516 <para>
517 <table rules="all">
518 <caption>Regionalized Service Endpoints</caption>
519 <thead>
520 <tr align="center">
521 <td colspan="2">Region</td>
522 <td colspan="5">Endpoint</td>
523 </tr>
524 </thead>
525 <tbody>
526 <tr align="left">
527 <td colspan="2">Chicago (ORD)</td>
528 <td colspan="5"
529 ><code>https://ord.databases.api.rackspacecloud.com/v1.0/</code><parameter>1234</parameter>/
530 </td>
531 </tr>
532 <tr align="left">
533 <td colspan="2">Dallas/Ft. Worth (DFW)</td>
534 <td colspan="5"
535 ><code>https://dfw.databases.api.rackspacecloud.com/v1.0/</code><parameter>1234</parameter>/
536 </td>
537 </tr>
538 <tr align="left">
539 <td colspan="2">London (LON)</td>
540 <td colspan="5">
541 <code>https://lon.databases.api.rackspacecloud.com/v1.0/</code><parameter>1234</parameter>/
542 </td>
543 </tr>
544 </tbody>
545 </table>
546 </para>
547 <note>
548 <title>Notes:</title>
549 <itemizedlist>
550 <listitem>
551 <para>Choose the endpoint from the table for the
552 datacenter where your Cloud resources are
553 located.</para>
554 </listitem>
555 <listitem>
556 <para>The Cloud Server that you use in <xref
557 linkend="Create_Cloud_Server"/> must be
558 located in the same datacenter where your
559 database resides.</para>
560 </listitem>
561 <listitem>
562 <para>All examples in this guide assume that you
563 are operating against the ORD datacenter,
564 however if you are using a different
565 datacenter, be sure to use the associated
566 endpoint from the table above instead.</para>
567 </listitem>
568 </itemizedlist>
569 </note>
570 <para>Replace the sample account ID number,
571 <parameter>1234</parameter>, with your actual account
572 number returned as part of the authentication response.
573 Use your actual account number wherever you see the field
574 <emphasis role="bold">your_acct_id</emphasis>
575 specified in this guide. Refer to <xref
576 linkend="Generating_Auth_Token"/>.</para>
577 <para>When making a Cloud Databases API call, place the
578 endpoint at the beginning of the request URL, for example:
579 (<code>https://ord.databases.api.rackspacecloud.com/v1.0/your_acct_id/</code>),
580 as you can see in the cURL List Flavors Details Request
581 examples in <xref linkend="List_Flavors"/>.</para>
582 </chapter>
583 <chapter xml:id="List_Flavors">
584 <title>List Flavors</title>
585 <para> A flavor is an available hardware configuration for a
586 database instance. Each flavor has a unique combination of
587 memory capacity and priority for CPU time. The larger the
588 flavor size you use, the larger the amount of RAM and
589 priority for CPU time your database instance will
590 receive.</para>
591 <para>You need to use the List Flavors API call
592 (<code>/flavors</code>) to find the available
593 configurations for your database instance, and then decide
594 which size you need.</para>
595 <para>This operation does not require a request body.</para>
596 <para>The following examples show the cURL requests for List
597 Flavors:</para>
598 <example>
599 <title>cURL List Flavors Request: XML</title>
600 <programlisting language="bash"><command>curl -i</command> \
601-H 'X-Auth-Token: <emphasis role="bold">your_auth_token</emphasis>' \
602<option>-H 'Accept: application/xml'</option> \
603<uri>'https://ord.databases.api.rackspacecloud.com/v1.0/</uri><emphasis role="bold">your_acct_id</emphasis><uri>/flavors'</uri></programlisting>
604 </example>
605 <example>
606 <title>cURL List Flavors Request: JSON</title>
607 <programlisting language="bash"><command>curl -i</command> \
608-H 'X-Auth-Token: <emphasis role="bold">your_auth_token</emphasis>' \
609<option>-H 'Accept: application/json'</option> \
610<uri>'https://ord.databases.api.rackspacecloud.com/v1.0/</uri><emphasis role="bold">your_acct_id</emphasis><uri>/flavors'</uri></programlisting>
611 </example>
612 <para>Remember to replace the names in the examples above with
613 their actual respective values for all the cURL examples
614 that follow:<itemizedlist spacing="compact">
615 <listitem>
616 <para><emphasis role="bold"
617 >your_auth_token</emphasis> &mdash; as
618 returned in your authentication response (see
619 the response examples in <xref
620 linkend="Generating_Auth_Token"/>)</para>
621 </listitem>
622 <listitem>
623 <para><emphasis role="bold"
624 >your_acct_id</emphasis> &mdash; as
625 returned in your authentication response (must
626 be replaced in the request URL)</para>
627 </listitem>
628 </itemizedlist></para>
629 <para>The following examples show the responses for List
630 Flavors:</para>
631 <example>
632 <title>List Flavors Response: XML</title>
633 <programlisting language="xml"><xi:include href="../../src/resources/samples/db-flavors-response.xml" parse="text"><xi:fallback>Missing code sample! <?rax fail?></xi:fallback></xi:include></programlisting>
634 </example>
635 <example>
636 <title>List Flavors Response: JSON</title>
637 <programlisting language="json"><xi:include href="../../src/resources/samples/db-flavors-response.json" parse="text"><xi:fallback>Missing code sample! <?rax fail?></xi:fallback></xi:include></programlisting>
638 </example>
639 <para>In the previous examples, you can see from the flavor
640 <code>name</code> that there are multiple flavors
641 available, including <code>medium</code> (with 1 virtual
642 CPU and 2 gigabytes of memory) and <code>tiny</code> (with
643 1 virtual CPU and 0.5 gigabytes of memory). </para>
644 <para>In this example, assume that you decide to use the tiny
645 flavor (id 1) to provide the needed capacity for your
646 database instance.</para>
647 <para>Notice that there are two kinds of link relations
648 associated with flavor resources. A <code>self</code> link
649 contains a <emphasis>versioned</emphasis> link to the
650 flavor resource. These links should be used in cases where
651 the link will be followed immediately (as you will see in
652 the next section). A <code>bookmark</code> link provides a
653 permanent link to a flavor resource that is appropriate
654 for long term storage and works across API
655 versions.</para>
656 </chapter>
657
658 <chapter xml:id="Create_DB_Instance">
659 <title>Create a Database Instance with a Database and a
660 User</title>
661 <para>A database instance is an isolated MySQL instance in
662 a single tenant environment on a shared physical host
663 machine. In the example below, you create a database
664 instance with a database and a user. The example instance
665 uses the tiny flavor and a volume size of 2 gigabytes
666 (GB). </para>
667 <para>Refer to <link
668 xlink:href="http://docs-beta.rackspace.com/cdb/api/v1.0/cdb-devguide/content/POST_createDatabase__version___accountID__instances__instanceId__databases_databases.html"
669 >Create Database</link> in the <citetitle>Cloud
670 Databases Developer Guide</citetitle> for the
671 restrictions for choosing the database name.</para>
672 <para>The example creates a database instance
673 <code>myrackinstance</code>, with the following: <itemizedlist>
674 <listitem>
675 <para>the tiny flavor</para>
676 </listitem>
677 <listitem>
678 <para>volume size of 2 gigabytes (GB)</para>
679 </listitem>
680 <listitem>
681 <para>a database named <code>sampledb</code> with:<itemizedlist>
682 <listitem>
683 <para><code>utf8</code> character
684 set</para>
685 </listitem>
686 <listitem>
687 <para><code>utf8_general_ci</code>
688 collation</para>
689 </listitem>
690 </itemizedlist></para>
691 </listitem>
692 <listitem>
693 <para>a user <code>simplestUser</code> with
694 password <code>password</code></para>
695 </listitem>
696 </itemizedlist>
697 </para>
698 <para>Notice that the request specifies the flavor reference
699 (<code>flavorRef</code>) to the tiny flavor (id 1)
700 that was returned by the List Flavors Details call:
701 <code>"https://ord.databases.api.rackspacecloud.com/v1.0/1234/flavors/1"</code>.
702 This is the <code>self</code> link that is the versioned
703 link to the flavor resource. Refer to the response
704 examples in <xref linkend="List_Flavors"/>.</para>
705 <para>The following examples show the cURL requests for Create
706 Instance:</para>
707 <example>
708 <title>cURL Create Instance Request: XML</title>
709 <programlisting language="bash"><command>curl</command> <option>-i</option> <option>-d</option> \
710'&lt;?xml version="1.0" ?>
711&lt;instance xmlns="http://docs.openstack.org/database/api/v1.0"
712 name="myrackinstance"
713 flavorRef=
714 "https://ord.databases.api.rackspacecloud.com/v1.0/<emphasis role="bold">your_acct_id</emphasis>/flavors/1">
715 &lt;databases>
716 &lt;database name="sampledb" character_set="utf8"
717 collate="utf8_general_ci" />
718 &lt;/databases>
719 &lt;users>
720 &lt;user name="simplestUser" password="password">
721 &lt;databases>
722 &lt;database name="sampledb"/>
723 &lt;/databases>
724 &lt;/user>
725 &lt;/users>
726 &lt;volume size="2" />
727&lt;/instance>' \
728-H 'X-Auth-Token: <emphasis role="bold">your_auth_token</emphasis>' \
729<option>-H 'Content-Type: application/xml'</option> \
730<option>-H 'Accept: application/xml'</option> \
731<uri>'https://ord.databases.api.rackspacecloud.com/v1.0/</uri><emphasis role="bold">your_acct_id</emphasis><uri>/instances'</uri></programlisting>
732 </example>
733 <example>
734 <title>cURL Create Instance Request: JSON</title>
735 <programlisting language="bash"><command>curl</command> <option>-i</option> <option>-d</option> \
736'{
737 "instance": {
738 "databases": [
739 {
740 "character_set": "utf8",
741 "collate": "utf8_general_ci",
742 "name": "sampledb"
743 }
744 ],
745 "flavorRef": "https://ord.databases.api.rackspacecloud.com/v1.0/<emphasis role="bold">your_acct_id</emphasis>/flavors/1",
746 "name": "myrackinstance",
747 "users": [
748 {
749 "databases": [
750 {
751 "name": "sampledb"
752 }
753 ],
754 "name": "simplestUser",
755 "password": "password"
756 }
757 ],
758 "volume":
759 {
760 "size": 2
761 }
762 }
763}' \
764-H 'X-Auth-Token: <emphasis role="bold">your_auth_token</emphasis>' \
765<option>-H 'Content-Type: application/json'</option> \
766<uri>'https://ord.databases.api.rackspacecloud.com/v1.0/</uri><emphasis role="bold">your_acct_id</emphasis><uri>/instances'</uri></programlisting>
767 </example>
768 <para>Remember to replace the names in the examples above with
769 their actual respective values for all the cURL examples
770 that follow:<itemizedlist spacing="compact">
771 <listitem>
772 <para><emphasis role="bold"
773 >your_auth_token</emphasis> &mdash; as
774 returned in your authentication response (see
775 the response examples in <xref
776 linkend="Generating_Auth_Token"/>)</para>
777 </listitem>
778 <listitem>
779 <para><emphasis role="bold"
780 >your_acct_id</emphasis> &mdash; as
781 returned in your authentication response (must
782 be replaced in the request URL)</para>
783 </listitem>
784 </itemizedlist></para>
785 <para>Remember to replace the account id shown in the
786 <code>flavorRef</code> property for the examples with
787 your actual account id:
788 <code>"https://ord.databases.api.rackspacecloud.com/v1.0/</code><emphasis
789 role="bold"
790 >your_acct_id</emphasis><code>/flavors/1"</code>.
791 Rather than the flavor URI shown in the previous sentence,
792 you can also pass the flavor id (integer) as the value for
793 flavorRef. For example, the flavor id for the flavor URI
794 shown above is "1". </para>
795 <para>The following examples show the Create Instance
796 responses:</para>
797
798 <example>
799 <title>Create Instance Response: XML</title>
800 <programlisting language="xml"><xi:include href="../../src/resources/samples/db-gs-create-database-instance-response.xml" parse="text"><xi:fallback>Missing code sample! <?rax fail?></xi:fallback></xi:include></programlisting>
801 </example>
802
803 <example>
804 <title>Create Instance Response: JSON</title>
805 <programlisting language="json"><xi:include href="../../src/resources/samples/db-gs-create-database-instance-response.json" parse="text"><xi:fallback>Missing code sample! <?rax fail?></xi:fallback></xi:include></programlisting>
806 </example>
807 <para>You will need to specify the instance id returned (in
808 the response examples above:
809 <code>id="d379ba5c-9a1f-4aa9-9a17-afe237d04c65"</code>)
810 on subsequent API calls that require it, for example List
811 Databases for Instance.</para>
812 <para>Note that the database and user are not listed in the
813 Create Instance responses. Next you will verify that both
814 were successfully created.<note>
815 <para> The operation of creating the database instance
816 may take up to several minutes. You will not be
817 able to perform the operations to List Databases
818 for Instance and List Users for Instance in the
819 sections that follow until the instance has ACTIVE
820 status. </para>
821 </note></para>
822 </chapter>
823 <chapter xml:id="List_DBS_For_Instance">
824 <title>List Databases for Instance</title>
825 <para>In this section you will list the databases in the
826 specified database instance.</para>
827 <para>This operation does not require a request body.</para>
828 <para xmlns="http://docbook.org/ns/docbook">The following
829 examples show the cURL requests for List Databases for
830 Instance:</para>
831 <example>
832 <title>cURL List Databases for Instance Request:
833 XML</title>
834 <programlisting language="bash"><command>curl</command> <option>-i</option> \
835-H 'X-Auth-Token: <emphasis role="bold">your_auth_token</emphasis>' \
836<option>-H 'Content-Type: application/xml'</option> \
837<option>-H 'Accept: application/xml'</option> \
838<uri>'https://ord.databases.api.rackspacecloud.com/v1.0/</uri><emphasis role="bold">your_acct_id</emphasis><uri>/instances/</uri><emphasis role="bold">instance_id</emphasis><uri>/databases'</uri></programlisting>
839 </example>
840 <example>
841 <?dbfo keep-together="always"?>
842 <title>cURL List Databases for Instance Request:
843 JSON</title>
844 <programlisting language="bash"><command>curl</command> <option>-i</option> \
845-H 'X-Auth-Token: <emphasis role="bold">your_auth_token</emphasis>' \
846<option>-H 'Content-Type: application/json'</option> \
847<uri>'https://ord.databases.api.rackspacecloud.com/v1.0/</uri><emphasis role="bold">your_acct_id</emphasis><uri>/instances/</uri><emphasis role="bold">instance_id</emphasis><uri>/databases'</uri></programlisting>
848 </example>
849 <para>Remember to replace the names in the examples above with
850 their actual respective values:<itemizedlist spacing="compact">
851 <listitem>
852 <para><emphasis role="bold"
853 >your_auth_token</emphasis> &mdash; as
854 returned in your authentication response (see
855 the examples in <xref
856 linkend="Generating_Auth_Token"/>)</para>
857 </listitem>
858 <listitem>
859 <para><emphasis role="bold"
860 >your_acct_id</emphasis> &mdash; as
861 returned in your authentication response (see
862 the examples in <xref
863 linkend="Generating_Auth_Token"/>)</para>
864 </listitem>
865 <listitem>
866 <para><emphasis role="bold">instance_id</emphasis>
867 &mdash; as returned in your create instance
868 response (see the examples in <xref
869 linkend="Create_DB_Instance"/>)</para>
870 </listitem>
871 </itemizedlist></para>
872 <para>The following examples show the responses for Create
873 User:</para>
874 <example>
875 <title>List Databases for Instance Response: XML</title>
876 <programlisting language="xml">HTTP/1.1 200 OK
877Content-Type: application/xml
878Content-Length: 109
879Date: Thu, 05 Apr 2012 18:20:18 GMT
880
881&lt;databases xmlns="http://docs.openstack.org/database/api/v1.0">
882 &lt;database name="sampledb"/>
883&lt;/databases>
884</programlisting>
885 </example>
886 <example>
887 <title>List Databases for Instance Response: JSON</title>
888 <programlisting language="json">HTTP/1.1 200 OK
889Content-Type: application/json
890Content-Length: 37
891Date: Thu, 05 Apr 2012 18:13:53 GMT
892
893{
894 "databases": [
895 {
896 "name": "sampledb"
897 }
898 ]
899}</programlisting>
900 </example>
901 <para>You can see that the database <code>sampledb</code> was
902 successfully created. Next you will list the users.</para>
903 </chapter>
904 <chapter xml:id="List_Users_DB_Instance">
905 <title>List Users in Database Instance</title>
906 <para>In this section you will list the users in the specified
907 database instance.</para>
908 <para>This operation does not require a request body.</para>
909 <para>The following examples show the cURL requests for List
910 Users in Database Instance:</para>
911 <example>
912 <title>cURL List Users in Database Instance Request:
913 XML</title>
914 <programlisting language="bash"><command>curl</command> <option>-i</option> \
915-H 'X-Auth-Token: <emphasis role="bold">your_auth_token</emphasis>' \
916<option>-H 'Content-Type: application/xml'</option> \
917<option>-H 'Accept: application/xml'</option> \
918<uri>'https://ord.databases.api.rackspacecloud.com/v1.0/</uri><emphasis role="bold">your_acct_id</emphasis><uri>/instances/</uri><emphasis role="bold">instance_id</emphasis><uri>/users'</uri></programlisting>
919 </example>
920 <example>
921 <?dbfo keep-together="always"?>
922 <title>cURL List Users in Database Instance Request:
923 JSON</title>
924 <programlisting language="bash"><command>curl</command> <option>-i</option> \
925-H 'X-Auth-Token: <emphasis role="bold">your_auth_token</emphasis>' \
926<option>-H 'Content-Type: application/json'</option> \
927<uri>'https://ord.databases.api.rackspacecloud.com/v1.0/</uri><emphasis role="bold">your_acct_id</emphasis><uri>/instances/</uri><emphasis role="bold">instance_id</emphasis><uri>/users'</uri></programlisting>
928 </example>
929 <para>Remember to replace the names in the examples above with
930 their actual respective values:<itemizedlist
931 spacing="compact">
932 <listitem>
933 <para><emphasis role="bold"
934 >your_auth_token</emphasis> &mdash; as
935 returned in your authentication response (see
936 the examples in <xref
937 linkend="Generating_Auth_Token"/>)</para>
938 </listitem>
939 <listitem>
940 <para><emphasis role="bold"
941 >your_acct_id</emphasis> &mdash; as
942 returned in your authentication response (see
943 the examples in <xref
944 linkend="Generating_Auth_Token"/>)</para>
945 </listitem>
946 <listitem>
947 <para><emphasis role="bold">instance_id</emphasis>
948 &mdash; as returned in your create instance
949 response (see the examples in <xref
950 linkend="Create_DB_Instance"/>)</para>
951 </listitem>
952 </itemizedlist></para>
953 <para>The following examples show the responses for List
954 Users in Database Instance:</para>
955 <example>
956 <title>List Users in Database Instance Response:
957 XML</title>
958 <programlisting language="xml">HTTP/1.1 200 OK
959Content-Type: application/xml
960Content-Length: 109
961Date: Thu, 05 Apr 2012 18:20:18 GMT
962
963&lt;?xml version="1.0" ?>
964&lt;users xmlns="http://docs.openstack.org/database/api/v1.0">
965 &lt;user name="simplestUser">
966 &lt;databases>
967 &lt;database>
968 &lt;name>
969 sampledb
970 &lt;/name>
971 &lt;/database>
972 &lt;/databases>
973 &lt;/user>
974&lt;/users>
975</programlisting>
976 </example>
977 <example>
978 <title>List Users in Database Instance Response:
979 JSON</title>
980 <programlisting language="json">HTTP/1.1 200 OK
981Content-Type: application/json
982Content-Length: 113
983Date: Thu, 05 Apr 2012 18:13:53 GMT
984
985{
986 "users": [
987 {
988 "databases": [
989 {
990 "name": "sampledb"
991 }
992 ],
993 "name": "simplestUser"
994 }
995 ]
996}</programlisting>
997 </example>
998 <para>You can see that the user <code>simplestUser</code> was
999 successfully created.</para>
1000 </chapter>
1001 <chapter xml:id="Create_Cloud_Server">
1002 <title>Create a New Cloud Server</title>
1003 <para>Create a Cloud Server (or use an existing Cloud Server)
1004 to access your database.</para>
1005 <note>
1006 <para>If you are using an existing Cloud Server on your
1007 account, skip this step and go directly to <xref
1008 linkend="Configure_Cloud_Server_DB"/>.</para>
1009 </note>
1010 <para>Create a Cloud Server using the Cloud Servers section of
1011 the Cloud Control Panel (login here: <link
1012 xlink:href="http://mycloud.rackspace.com/"
1013 >Control Panel Login</link>).</para>
1014 <procedure>
1015 <title>To create a Cloud Server using the Cloud Control
1016 Panel:</title>
1017 <step>
1018 <para>Click <guimenuitem>Servers</guimenuitem> to view
1019 the Cloud Servers page.</para>
1020 </step>
1021 <step>
1022 <para> Using the <guimenu>Region</guimenu> drop-down
1023 menu, select the appropriate region, depending on
1024 whether you want to create a first generation
1025 Cloud Server or a next generation Cloud Server.
1026 (The type of Cloud Server does not matter for this
1027 exercise.)</para>
1028 </step>
1029 <step>
1030 <para> Select an image from a list of different
1031 operating systems, including Linux Distributions
1032 and Windows Images:</para>
1033 <para><inlinemediaobject>
1034 <imageobject>
1035 <imagedata
1036 fileref="images/Choose_CS_Image_CCP.png"
1037 contentwidth="6in"/>
1038 </imageobject>
1039 </inlinemediaobject></para>
1040 </step>
1041 <step>
1042 <para> Specify the <guilabel>Server Name</guilabel>
1043 and select a <guilabel>Size</guilabel> for your
1044 Cloud Server, then click <guibutton>Create
1045 Server</guibutton>. </para>
1046 </step>
1047 </procedure>
1048 <note>
1049 <para>You can also create a Cloud Server using the Cloud
1050 Servers API. Refer to the <link
1051 xlink:href="http://docs.rackspace.com/">Next Generation Cloud
1052 Servers Developer Guide</link> for
1053 details.</para>
1054 </note>
1055 </chapter>
1056 <chapter xml:id="Configure_Cloud_Server_DB">
1057 <title>Configuring an Application to Use Your Cloud
1058 Database</title>
1059 <para>If you are configuring an application to use your
1060 database on a Cloud Server, you need to configure the
1061 application with the hostname for the database instance
1062 and user name / password for the database. Refer to the
1063 response examples in <xref linkend="Create_DB_Instance"/>
1064 for the <code>hostname</code> returned and the request
1065 examples for the user name and password you
1066 specified.</para>
1067 </chapter>
1068 <chapter xml:id="MySQL_GUI_Admin">
1069 <title>MySQL GUI Administration</title>
1070 <para> If you want to access your database using the command
1071 line MySQL client, then you have now completed the
1072 <citetitle>Getting Started</citetitle>.</para>
1073 <para>Otherwise, you can use a GUI tool such as phpMyAdmin to
1074 interact with your database instance. Common operations
1075 include managing databases, tables, fields, relations,
1076 indexes, users, and permissions. Included below is a
1077 procedure to set up phpMyAdmin on an Ubuntu 11.04 Cloud
1078 Server. </para>
1079 <para>For more detailed installation configuration
1080 instructions see the phpMyAdmin documentation at: <link
1081 xlink:href="http://www.phpmyadmin.net/documentation/"
1082 >http://www.phpmyadmin.net/documentation/</link>. <note>
1083