diff --git a/api-ref/src/docbkx/ch_database-v1.xml b/api-ref/src/docbkx/ch_database-v1.xml index c4d8e8a3a..356539a09 100644 --- a/api-ref/src/docbkx/ch_database-v1.xml +++ b/api-ref/src/docbkx/ch_database-v1.xml @@ -10,43 +10,50 @@ Database Service API v1.0 (CURRENT)
API versions + + Lists information for all Database Service API versions and shows + Database Service v1.0 details. + - + - +
Database instances (instances) + + Creates, lists, shows details for, attaches a configuration group + to, detaches a configuration group from, deletes, lists + configuration defaults, creates root, and determines whether root + is enables for instances. + - + - + - - + href="../wadls/databases-api/xsd/dbaas.wadl#instanceId"> + + - - - -
Database instance actions (action) + + Resizes instances and volumes and restarts instances. + @@ -58,11 +65,14 @@
Databases (databases) + + Creates, lists all, and deletes databases. + - + @@ -72,33 +82,45 @@
Users (users) + + Creates, lists all, and deletes users. + - + - + - + + + + +
Flavors (flavors) + + Lists all flavors and shows details for a flavor, by ID. + - + - +
- Datastores (datastores) + Data stores (datastores) + + Lists data store versions, lists parameters for data stores, and + shows parameter details for a data store version. + @@ -112,9 +134,12 @@ -
+
Configuration groups (configurations) + + Creates and lists all configuration groups. + diff --git a/api-ref/src/wadls/common_project.ent b/api-ref/src/wadls/common_project.ent index c8574627c..e7d3070e4 100644 --- a/api-ref/src/wadls/common_project.ent +++ b/api-ref/src/wadls/common_project.ent @@ -240,7 +240,7 @@ xmlns:wadl="http://wadl.dev.java.net/2009/02" xml:lang="EN"> - The date and time when the server was updated. + The date and time when the resource was updated. The date and time stamp format is - The date and time when the server, image, or backup was created. + The date and time when the resource was created. The date and time stamp format is + + + + + + + + + + %common; + + %common_project; +]> + + + + + + + + + &tenantIdRequestParameter; + + + &serverIdRequestParameter; + + + &attachment_idTemplateParameter; + + + + + + + + + + + + + + A list of volume attachments that are associated with a + server. + + + + + + + + + A list of volume attachments that are associated with a + server. + + + + + + + + + + + + + + Attaches a volume to a server. + + Preconditions + + + + You can attach a volume to a server with an + ACTIVE, PAUSED, + SHUTOFF, VERIFY_RESIZE, or + SOFT_DELETED status. + + + + + You can attach a volume to a server with a status that + is not locked. + + + + + You can attach a volume with a available status. + + + + + You can attach a volume when its volume type supports + volume attaching. + + + + Asynchronous Postconditions + + + + After successfully attaching a volume to a server, the + volume status changes to in-use. + + + + + You can see the attached volume when you + log in to the server. + + + + Troubleshooting + + + + If the volume status remains in available + state, the request failed. Ensure that you meet the + preconditions and run the request again. If the + request fails again, investigate the server and the + volume status. + + + + + + + + + + + + + The UUID of the volume to attach. + + + + + + + Name of the device such as, /dev/vdb. Omit or set this + parameter to null for auto-assignment, if supported. If you specify + this parameter, the device must not exist in the guest operating system. + + + + + + + A dictionary representation of a volume + attachment. + + + + + + + + + + + + &commonFaults; &getFaults; + &commonFaults; + &getFaults; &postPutFaults; &inProgressFault; + + + + Lists the volume attachments for a server. + + + + + + + + + + + + &commonFaults; &getFaults; + &commonFaults; + &getFaults; &postPutFaults; &inProgressFault; + + + + Shows details for a volume attachment. + + Preconditions + + + + The volume must be attached to the server. + + + + + + + + + + + + + + &commonFaults; &getFaults; + &commonFaults; + &getFaults; &postPutFaults; &inProgressFault; + + + + Detaches a volume from a server. + + Preconditions + + + + The volume must be attached to the server. + + + + + You can detach a volume when the server + status is ACTIVE, PAUSED, + SHUTOFF, VERIFY_RESIZE, or + SOFT_DELETED. + + + + + You can detach a volume when its status + is in-use. + + + + + You can detach a volume from a server with + a status that is not locked. + + + + + You cannot detach a root device volume. + + + + Asynchronous Postconditions + + After successfully detaching a volume, + its status changes to available. + + The detached volume is no longer visible on + the server. + + Troubleshooting + + + + If the volume status remains in available + state, the request failed. Ensure that you meet the + preconditions and run the request again. If the + request fails again, investigate whether another + operation is running that causes a race condition. + + + + + If you attempt to detach a root device volume, this + operation returns the Forbidden (403) + response code. + + + + + + + + + &commonFaults; + &getFaults; &postPutFaults; &inProgressFault; + diff --git a/api-ref/src/wadls/databases-api/xsd/common.ent b/api-ref/src/wadls/databases-api/xsd/common.ent index b8972274d..db1ff939f 100644 --- a/api-ref/src/wadls/databases-api/xsd/common.ent +++ b/api-ref/src/wadls/databases-api/xsd/common.ent @@ -68,5 +68,449 @@ - - '> + '> + + + + The account ID of the owner of the instance. + + +'> + + + + The ID for the database instance. + + +'> + + + + The name for the database. + + +'> + + + + The name for the user. + + +'> + + + + The ID for the flavor. + + +'> + + + + The name of the data store for which to list versions. + + +'> + + + + The UUID of the data store version. + + +'> + + + + The name of the parameter for which to show details. + + +'> + + + + + An instance object. + + +'> + + + + Reference (href), which is the actual URI to a + flavor as it appears in the list flavors response. + + + Rather than the flavor URI, you can also pass the + flavor ID (integer) as the flavorRef + value. For example, 1. + + +'> + + + + The volume size, in gigabytes (GB). A valid value + is from 1 to 50. + + +'> + + + + A databases object. + + +'> + + + + Name of the instance to create. A valid value is + up to 255 characters long. All characters are + permitted. + + +'> + + + + A database name. + + + You cannot use the lost+found, + information_schema, or mysql database + name to create a database because these names are reserved for + system databases. + + + Valid characters in a database name are: + + + + Upper and lower case letters. + + + Numbers. + + + @, ?, #, and spaces + except at the beginning or end of the database name. + + + _ is allowed anywhere in the database name. + + + + You cannot use these characters in a database name: + + + The maximum length of a database name is 64 characters. + + +'> + + + + A set of symbols and encodings. Default is utf8. + + + For information about supported character sets and collations, see Character Sets + and Collations in MySQL. + + +'> + + + + A set of rules for comparing characters in a character set. + Default is utf8_general_ci. + + + For information about supported character sets and collations, see Character Sets + and Collations in MySQL. + + +'> + + + + A users object. + + +'> + + + + The user name for the database on instance creation. + + +'> + + + + The password for those users on instance + creation. + + +'> + + + + + An instance object. + + +'> + + + + A flavor object, which includes the flavor ID + (integer) and flavor relative links. + + +'> + + + + The volume size, in gigabytes (GB). A valid value + is from 1 to 50. + + +'> + + + + A databases object. + + +'> + + + + Name of the instance to create. A valid value is + up to 255 characters long. All characters are + permitted. + + +'> + + + + A database name. + + + You cannot use the lost+found, + information_schema, or mysql database + name to create a database because these names are reserved for + system databases. + + + Valid characters in a database name are: + + + + Upper and lower case letters. + + + Numbers. + + + @, ?, #, and spaces + except at the beginning or end of the database name. + + + _ is allowed anywhere in the database name. + + + + You cannot use these characters in a database name: + + + The maximum length of a database name is 64 characters. + + +'> + + + + A set of symbols and encodings. Default is utf8. + + + For information about supported character sets and collations, see Character Sets + and Collations in MySQL. + + +'> + + + + A set of rules for comparing characters in a character set. + Default is utf8_general_ci. + + + For information about supported character sets and collations, see Character Sets + and Collations in MySQL. + + +'> + + + + A users object. + + +'> + + + + The user name for the database on instance creation. + + +'> + + + + The password for those users on instance + creation. + + +'> + diff --git a/api-ref/src/wadls/databases-api/xsd/dbaas.wadl b/api-ref/src/wadls/databases-api/xsd/dbaas.wadl index dff75dd0f..5e1736e1e 100644 --- a/api-ref/src/wadls/databases-api/xsd/dbaas.wadl +++ b/api-ref/src/wadls/databases-api/xsd/dbaas.wadl @@ -2,6 +2,8 @@ %common; + + %common_project; ]> - + - + - - - - The account ID of the owner of the instance. - - - + &accountIdTemplateParameter; - + - - - - The instance ID for the database - instance. - - - - + &instanceIdTemplateParameter; + @@ -75,94 +59,48 @@ - + - - The name for - the - database. - + &databaseNameTemplateParameter; - + - - The name for - the - user. - + &userNameTemplateParameter; - + - + - - The flavor ID for - the - flavor. - - + &flavorIdTemplateParameter; + - - - - The name of the data store whose versions - you want to list. - - - + &datastoreNameTemplateParameter; - - - - The ID of the data store version. - - - + &datastoreVersionIdTemplateParameter; - - - - Name of the parameter whose details you want. - - - + ¶meterNameTemplateParameter; @@ -184,19 +122,19 @@ --> - + Shows details for the Database - Service API v1.0. + xmlns="http://docbook.org/ns/docbook"> + + Shows details for the Database Service API v1.0. + + href="samples/db-version-request-json-http.txt"/> @@ -210,20 +148,21 @@ href="samples/db-version-response.json"/> - &commonFaults; &getFaults; - + &commonFaults; &getFaults; + + Lists information about all Database - Service API versions. + xmlns="http://docbook.org/ns/docbook"> + + Lists information about all Database Service API versions. + + href="samples/db-versions-request-json-http.txt"/> @@ -237,7 +176,8 @@ href="samples/db-versions-response.json"/> - &commonFaults; &getFaults; + &commonFaults; &getFaults; + - Asynchronously provisions a new database instance. You must + Asynchronously provisions a database instance. You must specify a flavor and a volume size. The service provisions the instance with a volume of the requested size, which serves as storage for the database instance. @@ -257,14 +197,13 @@ You can create only one database instance per - POST request. + &POST; request. You can create a database instance with one or - more databases, and users associated to those - databases. + more databases. You associate users with each database. @@ -285,101 +224,17 @@ - - - - An instance object. - - - - - - - Reference (href), which is the actual URI to a - flavor as specified in the response from the list - flavors API call. - - - Rather than the flavor URI, you can also pass the - flavor id (integer) as the value for - flavorRef. For example, the flavor ID - for the flavor URI shown above is 1. - - - - - - - The volume size, in gigabytes (GB). A valid value - is from 1 to 50. - - - - - A databases - object. - - - - - Name of the instance to create. A valid value is - up to 255 characters long. All characters are - permitted. - - - - - Specifies database names - for creating databases on instance - creation. - - - Set of symbols and - encodings. The default character set is - utf8. - - - Set of rules for comparing - characters in a character set. The default - value for collate is - utf8_general_ci. - - - A users - object. - - - The user name for the - database on instance - creation. - - - The password for those - users on instance - creation. - + &instanceRequestParameter; + &flavorRefRequestParameter; + &sizeRequestParameter; + &databasesRequestParameter; + &instance-nameRequestParameter; + &databaseNameRequestParameter; + &characterSetRequestParameter; + &collateRequestParameter; + &usersRequestParameter; + &user-nameRequestParameter; + &user-passwordRequestParameter; @@ -394,17 +249,40 @@ The previous response examples show resources that contain links to themselves that enable a client to easily obtain resource URIs rather than construct - them. There are two kinds of link relations associated - with resources. A self link contains a - versioned link to the resource. - These links should be used in cases where the link - will be followed immediately. A bookmark - link provides a permanent link to a resource that is - appropriate for long-term storage. + them. Resources can have these link relations: + + + + A self link contains a + versioned link to the resource. + Use these links in cases where the link + will be followed immediately. + + + + + A bookmark + link provides a permanent link to a resource that is + appropriate for long-term storage. + + + + &instanceResponseParameter; + &createdResponseParameter; + &flavorResponseParameter; + &databasesResponseParameter; + &instance-nameResponseParameter; + &databaseNameResponseParameter; + &characterSetResponseParameter; + &collateResponseParameter; + &usersResponseParameter; + &user-nameResponseParameter; + &updatedResponseParameter; - &commonFaults; &getFaults; + &commonFaults; &getFaults; + --> - This operation is not permitted when the instance state is - either REBUILDING or BUILDING. + You cannot complete this operation when the instance state + is either REBUILDING or + BUILDING. @@ -427,8 +306,7 @@ + href="samples/db-delete-instance-request-json-http.txt" /> @@ -438,12 +316,11 @@ + href="samples/db-delete-instance-response-json-http.txt"/> &getFaults; - + @@ -459,8 +336,7 @@ + href="samples/db-instances-index-request-json-http.txt"/> @@ -475,8 +351,9 @@ /> - &commonFaults; &getFaults; - + &commonFaults; &getFaults; + + @@ -495,21 +372,20 @@ After instance creation, the used value is greater than 0, which is expected and due to the automatic creation of non-empty transaction logs for MySQL - optimization. The used attribute is - not returned in the response when the - instance status is BUILD, - REBOOT, RESIZE, or - ERROR. + optimization. The response does not include the + used attribute when the instance status is + BUILD, REBOOT, + RESIZE, or ERROR. - The list operations return a DNS-resolvable host name that is - associated with the database instance rather than an IP - address. Because the host name always resolves to the correct - IP address for the database instance, you do not need to - maintain the mapping. Although the IP address might change - when you resize, migrate, or perform other operations, the - host name always resolves to the correct database instance. + The list operations return a DNS-resolvable host name for the + database instance rather than an IP address. Because the host + name always resolves to the correct IP address for the + database instance, you do not need to maintain the mapping. + Although the IP address might change when you resize, migrate, + or perform other operations, the host name always resolves to + the correct database instance. @@ -534,7 +410,8 @@ /> - &commonFaults; &getFaults; + &commonFaults; &getFaults; + - If the operation succeeds, it returns a 202 Accepted response. + If the operation succeeds, it returns the Accepted + (202) response code. @@ -663,148 +541,12 @@ - - Creates a database within an - instance. + + Creates a database within an instance. - This operation creates a database within an instance. + The name of the database is a required attribute. - - The name of the - database is a required attribute. - - - You can specify these additional attributes for each database: - collate and character_set. - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Required and optional attributes for creating a database
NameDescriptionRequired
nameSpecifies the database name - for creating the database. See the request - examples for the required xml/json - format.Yes
character_setSet of symbols and encodings. - The default character set is - utf8.No
collateSet of rules for comparing - characters in a character set. The default - value for collate is - utf8_general_ci.No
- - For information about supported character sets and collations, - see the MySQL documentation at Character - Sets and Collations in MySQL. - - - - The lost+found, - information_schema, and mysql - database names are reserved and cannot be used to create - databases. - - - - See the following tables for information about characters that - are valid for creating database names. - - - - - - - - - - - - - - - - - - - - - - -
Valid characters in a database name
Character
Letters (upper and lower cases - allowed)
Numbers
'@', '?', '#', and spaces are allowed, but - not at the - beginning and end of the database - name
'_' is allowed anywhere in the database - name
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Characters that cannot be used in a database name
Character
Single quotes
Double quotes
Back quotes
Semicolons
Commas
Back slashes
Forward slashes
- - - - - - - - - - - - -
Length restrictions for database name
RestrictionValue
Database-name maximum length64
 + &databaseNameRequestParameter; + &characterSetRequestParameter; + &collateRequestParameter; @@ -828,17 +573,23 @@ /> - &commonFaults; &getFaults; - + &commonFaults; &getFaults; + + Lists databases for an - instance. - This operation returns - only the user-defined databases, not the system - databases. The system databases (mysql, - information_schema, lost+found) can only be viewed - by a database administrator. + xmlns="http://docbook.org/ns/docbook"> + + Lists databases for an instance. + + + + This operation returns only the user-defined databases + and not the system databases. Only the database + administrator can view the mysql, + information_schema, and + lost+found system databases. + + @@ -862,14 +613,18 @@ /> - &commonFaults; &getFaults; + &commonFaults; &getFaults; + Deletes a - database. - Note that all data associated with the - database is also deleted. + xmlns="http://docbook.org/ns/docbook"> + + Deletes a database. + + + This operation also deletes all data that is associated with + the database. + @@ -890,18 +645,21 @@ /> - &commonFaults; &getFaults; + &commonFaults; &getFaults; + Creates a user for a database instance. - Asynchronously provisions a new user for the - database instance based on the configuration defined - in the request object. After the request is validated - and progress begins on the provisioning process, - a 202 Accepted response object is returned. + + Asynchronously provisions a new user for the database instance + by using the configuration that you define in the request + object. After the API validates the request and starts + progress on the provisioning process, the call returns the + Accepted (202) response code. + - If the corresponding request cannot be fulfilled due - to insufficient or invalid data, an HTTP 400 "Bad - Request" error response is returned with information - regarding the nature of the failure. Failures in the - validation process are non-recoverable and require the - caller to correct the cause of the failure and POST - the request again. - The following table lists the required attributes - for creating user. See the request examples for the - required xml/json format: + + If the API cannot fulfill the corresponding request due to + insufficient data or data that is not valid, the API returns + the Bad Request (400)response code with + information about the nature of the failure. You cannot + recover from validation errors. You must correct the cause of + the failure and the request again. + + + This table lists the required attributes for creating users: + - + - + @@ -952,22 +711,27 @@
Required attributes for creating a userRequired attributes for user
Applies ToApplies to Name Description Required
- Notes + + Notes + - A user is granted all privileges on the - specified databases. + + The operation grants the user all privileges on the databases. + - The following user name is reserved and - cannot be used for creating users: - root. + + Do not use the root user name, which is reserved. + - - See the following tables for information about - characters that are valid/invalid for creating - database names, user names, and passwords. + + + + These tables list the valid characters for database names, + user names, and passwords. + - + @@ -983,17 +747,17 @@ - -
Valid characters in a database name, user name, and passwordValid characters in database name, user name, and password
Numbers
'@', '?', '#', and spaces are allowed, but + @, ?, #, and spaces are allowed, but not at the beginning and end of the database name, user name, and password
"_" is allowed anywhere in the database + _ is allowed anywhere in the database name, user name, and password
- @@ -1070,24 +834,27 @@ /> - &commonFaults; &getFaults; - + &commonFaults; &getFaults; + + - Lists the users in a database instance, along with the - associated databases for that user. + Lists the users in a database instance and the associated + databases for that user. - This operation does not return the system users (database - administrators that administer the health of the - database). Also, this operation returns the "root" user - only if "root" user is enabled. + This operation does not return system users. A system + user is a database administrator who administers the + health of the database. Also, this operation returns the + root user only if it is enabled. - The following notes apply - to MySQL users: + + The following notes apply to MySQL users: + + User names can be up to 16 characters long. @@ -1124,24 +891,26 @@ href="samples/db-list-users-response.json"/> - &commonFaults; &getFaults; + &commonFaults; &getFaults; + Deletes a user for a database instance. - There is a bug in a Python library that - Rackspace is using that can cause incorrect user - deletions to occur if a period (.) is used in the - user name. In this case, the user name is - truncated to remove the portion of the name from - the period to the end, leaving only the portion - from the beginning up to the period. For example, - for a user named "my.userA", the bug would - truncate the user name to "my", and if the user - "my" exists, that user will be incorrectly - deleted. To avoid the problem, do not use periods - in user names. + + + Do not use periods in user names. A bug in a Python + library that Rackspace uses that can cause incorrect user + deletions to occur if you use a period (.) in the user + name. In this case, the bug in the library truncates the + user name to the portion from the beginning up to the + period. For example, for the my.userA user, + the bug truncates the user name to my, and if + the user exists, that user is incorrectly + deleted. + + @@ -1162,27 +931,30 @@ /> - &commonFaults; &getFaults; + &commonFaults; &getFaults; + Enables the root user for a - database instance and returns the root - password.This operation enables login - from any host for the root user and provides the user - with a generated root password. + xmlns="http://docbook.org/ns/docbook"> + + Enables the root user for a database instance and returns the + root password. + + + This operation generates a root password for the root user and + enables the root user to log in from any host. + - Changes that you make as a root user can have detrimental - effects on the database instance and unpredictable - behavior for API operations. When you enable the root - user, you accept the possibility that we will not be able - to support your database instance. We may not be able to - assist you if you change core MySQL settings. These - changes can be, but are not limited to, turning off bin - logs, removing users that we use to access your instance, - and so on. + Changes that you make as a root user can impact the + database instance and API operations in unpredictable and + detrimental ways. When you enable the root user, you + accept the possibility that we cannot support your + database instance. We might not be able to assist you if you + change core MySQL settings. These changes can be, but are + not limited to, turning off bin logs, removing users that + we use to access your instance, and so on. @@ -1208,7 +980,8 @@ /> - &commonFaults; &getFaults; + &commonFaults; &getFaults; + + href="samples/db-check-root-user-request-json-http.txt"/> @@ -1243,9 +1015,10 @@ /> - &commonFaults; &getFaults; + &commonFaults; &getFaults; + - + Lists information for all available @@ -1280,19 +1053,25 @@ href="samples/db-flavors-response.json"/> - &commonFaults; &getFaults; - + &commonFaults; &getFaults; + + Shows flavor details with details of the RAM. - This resource is identical to the flavors found in - the OpenStack Compute API, but without the disk - property. - The flavorId parameter should be an integer. - If a floating point value is used for the flavorId - parameter, the decimal portion is truncated and - the integer portion is used as the value of the - flavorId. + + This resource is identical to the flavors found in the + OpenStack Compute API, but without the disk property. + + + + The flavorId parameter must be an integer + value. If you use a floating point value for this + parameter, this call truncates the decimal portion and + uses the integer portion as the flavorId + value. + + Writer: need to confirm that this behavior is not changed in subsequent releases, and if it is prevented, remove the Note above. @@ -1446,7 +1225,7 @@ xml:lang="EN"> Data store assigned to the configuration group. - Required if default data store is not configured. + Required if you did not configure the default data store. @@ -1596,9 +1375,9 @@ an instance. - When you pass in only an instance ID and omit the configuration ID, - this operation detaches any configuration group - that was attached to the instance. + When you pass in only an instance ID and omit the + configuration ID, this operation detaches any configuration + group that was attached to the instance. @@ -1615,7 +1394,8 @@ - To detach a configuration group, set the configuration parameter to null. + To detach a configuration group, set the + configuration parameter to null.
Characters that cannot be used in a database name, user name, and + Characters that are not allowed in database name, user name, and password