Adds the api-ref migrated RST + YAML files

With this email[0], you must migrate API reference docs into RST. The
conf.py and the tox environment are also cribbed from nova.

Still need to retain the install_command in tox.ini, otherwise the
api-ref job fails.

[0] http://lists.openstack.org/pipermail/openstack-dev/2016-May/093765.html

Co-Authored-By: Anne Gentle <agentle@cisco.com>
Co-Authored-By: Amrith Kumar <amrith@tesora.com>

Change-Id: I3315261aa18729fa7a6aa79d4a1d6c24de1e2c6b

CONTRIBUTING.rst

@@ -143,59 +143,14 @@ process.
 Trove Documentation
 ===================
 
-This repository also contains the following OpenStack manual:
+This repository also contains the Database Services API Reference.
+To build the API reference, run::
 
-* Database Services API Reference
+    $ tox -e api-ref
 
-Prerequisites for Building the Documentation
---------------------------------------------
-`Apache Maven <http://maven.apache.org/>`_ must be installed to build the
-documentation.
+The generated documentation is found::
 
-To install Maven 3 for Ubuntu 12.04 and later, and Debian wheezy and later::
-
-    apt-get install maven
-
-On Fedora 15 and later::
-
-    yum install maven3
-
-Building
---------
-The manuals are in the ``apidocs`` directory.
-
-To build a specific guide, look for a ``pom.xml`` file within a subdirectory,
-then run the ``mvn`` command in that directory. For example::
-
-    cd apidocs
-    mvn clean generate-sources
-
-The generated PDF documentation file is::
-
-    apidocs/target/docbkx/webhelp/cdb-devguide/cdb-devguide-reviewer.pdf
-
-The root of the generated HTML documentation is::
-
-    apidocs/target/docbkx/webhelp/cdb-devguide/content/index.html
-
-Testing of changes and building of the manual
-----------------------------------------------
-
-Install the python tox package and run ``tox`` from the top-level
-directory to use the same tests that are done as part of our Jenkins
-gating jobs.
-
-If you like to run individual tests, run:
-
- * ``tox -e checkniceness`` - to run the niceness tests
- * ``tox -e checksyntax`` - to run syntax checks
- * ``tox -e checkdeletions`` - to check that no deleted files are referenced
- * ``tox -e checkbuild`` - to actually build the manual
-
-tox will use the `openstack-doc-tools package
-<https://github.com/openstack/openstack-doc-tools>`_ for execution of
-these tests. openstack-doc-tools has a requirement on maven for the
-build check.
+    api-ref/html/index.html
 
 Testing
 =======

api-ref/source/api-versions.inc

@@ -0,0 +1,76 @@
+.. -*- rst -*-
+
+============
+API versions
+============
+
+Lists information for all Database Service API versions and shows
+Database Service v1.0 details.
+
+
+List versions
+=============
+
+.. rest_method::  GET /
+
+Lists information about all Database Service API versions.
+
+
+Normal response codes: 200
+Error response codes:413,405,404,403,401,400,422,503,500,501,
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/db-versions-response.json
+   :language: javascript
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Show version details
+====================
+
+.. rest_method::  GET /v1.0
+
+Shows details for the Database Service API v1.0.
+
+
+Normal response codes: 200
+Error response codes:413,405,404,403,401,400,422,503,500,501,
+
+
+
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/db-version-response.json
+   :language: javascript
+
+
+
+
+
+
+
+
+
+
+
+
+

api-ref/source/conf.py

@@ -0,0 +1,222 @@
+# -*- coding: utf-8 -*-
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+#
+# trove documentation build configuration file, created by
+# sphinx-quickstart on Sat May  1 15:17:47 2010.
+#
+# This file is execfile()d with the current directory set to
+# its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import os
+import subprocess
+import sys
+import warnings
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+sys.path.insert(0, os.path.abspath('../../'))
+sys.path.insert(0, os.path.abspath('../'))
+sys.path.insert(0, os.path.abspath('./'))
+
+# -- General configuration ----------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+
+extensions = [
+    'os_api_ref',
+    'oslosphinx',
+]
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#
+# source_encoding = 'utf-8'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'Database API Reference'
+copyright = u'2010-present, OpenStack Foundation'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+from trove.version import version_info
+# The full version, including alpha/beta/rc tags.
+release = version_info.release_string()
+# The short X.Y version.
+version = version_info.version_string()
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+# today = ''
+# Else, today_fmt is used as the format for a strftime call.
+# today_fmt = '%B %d, %Y'
+
+# The reST default role (used for this markup: `text`) to use
+# for all documents.
+# default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+# add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+add_module_names = False
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# -- Options for man page output ----------------------------------------------
+
+# Grouping the document tree for man pages.
+# List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual'
+
+
+# -- Options for HTML output --------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  Major themes that come with
+# Sphinx are currently 'default' and 'sphinxdoc'.
+# html_theme_path = ["."]
+# html_theme = '_theme'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+# html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+# html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+# html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+# html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+# html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+# html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+# html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+# html_last_updated_fmt = '%b %d, %Y'
+git_cmd = ["git", "log", "--pretty=format:'%ad, commit %h'", "--date=local",
+           "-n1"]
+try:
+    html_last_updated_fmt = subprocess.Popen(
+        git_cmd, stdout=subprocess.PIPE).communicate()[0]
+except Exception:
+    warnings.warn('Cannot get last updated time from git repository. '
+                  'Not setting "html_last_updated_fmt".')
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+# html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+# html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+# html_additional_pages = {}
+
+# If false, no module index is generated.
+# html_use_modindex = True
+
+# If false, no index is generated.
+# html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+# html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+# html_show_sourcelink = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+# html_use_opensearch = ''
+
+# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
+# html_file_suffix = ''
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'trovedoc'
+
+
+# -- Options for LaTeX output -------------------------------------------------
+
+# The paper size ('letter' or 'a4').
+# latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+# latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass
+# [howto/manual]).
+latex_documents = [
+    ('index', 'Trove.tex', u'OpenStack Database API Documentation',
+     u'OpenStack Foundation', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+# latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+# latex_use_parts = False
+
+# Additional stuff for the LaTeX preamble.
+# latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+# latex_appendices = []
+
+# If false, no module index is generated.
+# latex_use_modindex = True

api-ref/source/configurations.inc

@@ -0,0 +1,313 @@
+.. -*- rst -*-
+
+=====================================
+Configuration groups (configurations)
+=====================================
+
+Creates and lists all configuration groups.
+
+
+Create configuration group
+==========================
+
+.. rest_method::  POST /v1.0/{accountId}/configurations
+
+Creates a configuration group.
+
+
+Normal response codes: 200
+Error response codes:413,405,404,403,401,400,422,503,500,501,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - datastore: datastore
+   - values: values
+   - name: name
+   - accountId: accountId
+
+Request Example
+---------------
+
+.. literalinclude:: samples/db-create-config-group-request.json
+   :language: javascript
+
+
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/db-create-config-group-response.json
+   :language: javascript
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+List configuration groups
+=========================
+
+.. rest_method::  GET /v1.0/{accountId}/configurations
+
+Lists all configuration groups.
+
+The list includes the associated data store and data store version
+for each configuration group.
+
+
+Normal response codes: 200
+Error response codes:413,405,404,403,401,400,422,503,500,501,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - accountId: accountId
+
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/db-list-cfg-groups-response.json
+   :language: javascript
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+List configuration group instances
+==================================
+
+.. rest_method::  GET /v1.0/{accountId}/configurations/{configId}/instances
+
+Lists the instances associated with the specified configuration group.
+
+
+Normal response codes: 200
+Error response codes:413,405,404,403,401,400,422,503,500,501,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - configId: configId
+   - accountId: accountId
+
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/db-config-group-instances-response.json
+   :language: javascript
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Delete configuration group
+==========================
+
+.. rest_method::  DELETE /v1.0/{accountId}/configurations/{configId}
+
+Deletes a configuration group.
+
+Error response codes:202,413,405,404,403,401,400,422,503,500,501,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - configId: configId
+   - accountId: accountId
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Patch configuration group
+=========================
+
+.. rest_method::  PATCH /v1.0/{accountId}/configurations/{configId}
+
+Sets new values for a configuration group.
+
+
+Normal response codes: 200
+Error response codes:413,405,404,403,401,400,422,503,500,501,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - values: values
+   - configId: configId
+   - accountId: accountId
+
+Request Example
+---------------
+
+.. literalinclude:: samples/db-patch-config-group-request.json
+   :language: javascript
+
+
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/db-patch-config-group-response-json-http.txt
+   :language: javascript
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Show configuration group details
+================================
+
+.. rest_method::  GET /v1.0/{accountId}/configurations/{configId}
+
+Lists details about a configuration group, including its values.
+
+
+Normal response codes: 200
+Error response codes:413,405,404,403,401,400,422,503,500,501,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - configId: configId
+   - accountId: accountId
+
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/db-config-group-details-response.json
+   :language: javascript
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Update configuration group
+==========================
+
+.. rest_method::  PUT /v1.0/{accountId}/configurations/{configId}
+
+Sets new values for a configuration group. Also lets you change the name and description of the configuration group.
+
+Error response codes:202,413,405,404,403,401,400,422,503,500,501,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - values: values
+   - description: description
+   - name: name
+   - configId: configId
+   - accountId: accountId
+
+Request Example
+---------------
+
+.. literalinclude:: samples/db-update-config-group-request.json
+   :language: javascript
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

api-ref/source/database-instance-actions.inc

@@ -0,0 +1,269 @@
+.. -*- rst -*-
+
+==================================
+Database instance actions (action)
+==================================
+
+Resizes instances and volumes and restarts instances.
+
+
+Restart instance
+================
+
+.. rest_method::  POST /v1.0/{accountId}/instances/{instanceId}/action
+
+Restarts the database service for an instance.
+
+The restart operation restarts only the MySQL instance. Restarting
+MySQL erases any dynamic configuration settings that you make in
+MySQL.
+
+The MySQL service is unavailable until the instance restarts.
+
+If the operation succeeds, it returns the ``Accepted (202)``
+response code.
+
+Error response codes:202,413,415,405,404,403,401,400,422,503,500,501,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - instanceId: instanceId
+   - accountId: accountId
+
+Request Example
+---------------
+
+.. literalinclude:: samples/db-instance-restart-request.json
+   :language: javascript
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Resize instance
+===============
+
+.. rest_method::  POST /v1.0/{accountId}/instances/{instanceId}/action
+
+Resizes the memory for an instance.
+
+If you provide a valid ``flavorRef``, this operation changes the
+memory size of the instance, and restarts MySQL.
+
+Error response codes:202,413,415,405,404,403,401,400,422,503,500,501,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - instanceId: instanceId
+   - accountId: accountId
+
+Request Example
+---------------
+
+.. literalinclude:: samples/db-instance-resize-instance-request.json
+   :language: javascript
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Resize instance volume
+======================
+
+.. rest_method::  POST /v1.0/{accountId}/instances/{instanceId}/action
+
+Resizes the volume that is attached to an instance.
+
+You can use this operation to increase but not decrease the volume
+size. A valid volume size is an integer value in gigabytes (GB).
+
+You cannot increase the volume to a size that is larger than the
+API volume size limit.
+
+If this operation succeeds, it returns a 202 Accepted response.
+
+Error response codes:202,413,415,405,404,403,401,400,422,503,500,501,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - instanceId: instanceId
+   - accountId: accountId
+
+Request Example
+---------------
+
+.. literalinclude:: samples/db-instance-resize-volume-request.json
+   :language: javascript
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Promote instance to replica source
+==================================
+
+.. rest_method::  POST /v1.0/{accountId}/instances/{instanceId}/action
+
+Promotes a replica.
+
+If you have set up replication, and the base instance is still
+reachable, you can use this operation to promote a replica to be
+the new base instance.
+
+This can be useful if you want to make a configuration change to
+the base instance that your replicas are replicating from. For
+example, you might want to increase the disk or CPU capacity. If
+you made the change on the base instance directly, you would need
+to take the base instance down for the duration of the operation.
+Instead, you can create a replica, make the configuration change on
+the replica, and then promote the replica to become the new base
+instance.
+
+For ``instanceId``, pass in the instance ID of the replica you want
+to promote.
+
+Error response codes:202,413,415,405,404,403,401,400,422,503,500,501,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - instanceId: instanceId
+   - accountId: accountId
+
+Request Example
+---------------
+
+.. literalinclude:: samples/db-instance-promote-replica-request.json
+   :language: javascript
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Delete replication base instance
+================================
+
+.. rest_method::  POST /v1.0/{accountId}/instances/{instanceId}/action
+
+Deletes the base instance in a replication set.
+
+If the base instance becomes unreachable, you can use this
+operation to delete the base instance.
+
+This operation:
+
+- Finds the replica that has processed the greatest number of
+  transactions and picks that replica to use as the new base
+  instance.
+
+- Transfers the public IP of the old base instance to the new base
+  instance (which is the newly-promoted replica).
+
+- Deletes the old base instance.
+
+- Takes all the instances in the replication set and makes them
+  start replicating from the new base instance.
+
+For ``instanceId``, pass in the instance ID of the unreachable base
+instance.
+
+Error response codes:202,413,415,405,404,403,401,400,422,503,500,501,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - instanceId: instanceId
+   - accountId: accountId
+
+Request Example
+---------------
+
+.. literalinclude:: samples/db-instance-eject-replica-request.json
+   :language: javascript
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

api-ref/source/database-instances.inc

@@ -0,0 +1,425 @@
+.. -*- rst -*-
+
+==============================
+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.
+
+
+Delete database instance
+========================
+
+.. rest_method::  DELETE /v1.0/{accountId}/instances/{instanceId}
+
+Deletes a database instance, including any associated data.
+
+This operation does not delete any read slaves.
+
+You cannot complete this operation when the instance state is
+either ``REBUILDING`` or ``BUILDING``.
+
+Error response codes:202,413,405,404,403,401,400,422,503,500,501,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - instanceId: instanceId
+   - accountId: accountId
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Show database instance details
+==============================
+
+.. rest_method::  GET /v1.0/{accountId}/instances/{instanceId}
+
+Shows database instance details.
+
+Lists the status and details of the database instance.
+
+Lists the volume size in gigabytes (GB) and the approximate GB
+used.
+
+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 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 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.
+
+
+Normal response codes: 200
+Error response codes:413,405,404,403,401,400,422,503,500,501,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - instanceId: instanceId
+   - accountId: accountId
+
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/db-instance-status-detail-response.json
+   :language: javascript
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Attach configuration group
+==========================
+
+.. rest_method::  PUT /v1.0/{accountId}/instances/{instanceId}
+
+Attaches a configuration group to an instance.
+
+Error response codes:202,413,415,405,404,403,401,400,422,503,500,501,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - configuration: configuration
+   - instanceId: instanceId
+   - accountId: accountId
+
+Request Example
+---------------
+
+.. literalinclude:: samples/db-attach-config-group-request.json
+   :language: javascript
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Detach configuration group
+==========================
+
+.. rest_method::  PUT /v1.0/{accountId}/instances/{instanceId}
+
+Detaches a configuration group from 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.
+
+Error response codes:202,413,415,405,404,403,401,400,422,503,500,501,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - configuration: configuration
+   - instanceId: instanceId
+   - accountId: accountId
+
+Request Example
+---------------
+
+.. literalinclude:: samples/db-detach-config-group-request.json
+   :language: javascript
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Detach replica
+==============
+
+.. rest_method::  PATCH /v1.0/{accountId}/instances/{instanceId}
+
+Detaches a replica from its replication source.
+
+If you created an instance that is a replica of a source instance,
+you can detach the replica from the source. This can be useful if
+the source becomes unavailable. In this case, you can detach the
+replica from the source, making the replica a standalone database
+instance. You can then take the new standalone instance and create
+a new replica of that instance.
+
+Error response codes:202,413,415,405,404,403,401,400,422,503,500,501,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - replica_of: replica_of
+   - slave_of: slave_of
+   - instanceId: instanceId
+   - accountId: accountId
+
+Request Example
+---------------
+
+.. literalinclude:: samples/db-detach-replica-request.json
+   :language: javascript
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Create database instance
+========================
+
+.. rest_method::  POST /v1.0/{accountId}/instances
+
+Creates a database instance.
+
+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.
+
+ **Notes**
+
+- You can create only one database instance per POST request.
+
+- You can create a database instance with one or more databases. You
+  associate users with each database.
+
+- The default binding for the MySQL instance is port 3306.
+
+
+Normal response codes: 200
+Error response codes:413,405,404,403,401,400,422,503,500,501,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - users: users
+   - password: password
+   - datastore_version: datastore_version
+   - name: name
+   - flavorRef: flavorRef
+   - characterSet: characterSet
+   - replica_count: replica_count
+   - instance: instance
+   - collate: collate
+   - databases: databases
+   - datastore: datastore
+   - configuration: configuration
+   - type: type
+   - replica_of: replica_of
+   - size: size
+   - accountId: accountId
+
+Request Example
+---------------
+
+.. literalinclude:: samples/db-create-instance-request.json
+   :language: javascript
+
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - updated: updated
+   - name: name
+   - created: created
+   - characterSet: characterSet
+   - instance: instance
+   - collate: collate
+   - databases: databases
+   - flavor: flavor
+   - users: users
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/db-create-instance-response.json
+   :language: javascript
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+List database instances
+=======================
+
+.. rest_method::  GET /v1.0/{accountId}/instances
+
+Lists information, including status, for all database instances.
+
+Lists status and information for all database instances.
+
+
+Normal response codes: 200
+Error response codes:413,405,404,403,401,400,422,503,500,501,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - accountId: accountId
+
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/db-instances-index-response.json
+   :language: javascript
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+List configuration defaults
+===========================
+
+.. rest_method::  GET /v1.0/{accountId}/instances/{instanceId}/configuration
+
+Lists the configuration defaults for an instance.
+
+
+Normal response codes: 200
+Error response codes:413,405,404,403,401,400,422,503,500,501,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - instanceId: instanceId
+   - accountId: accountId
+
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/db-list-cfg-defaults-response.json
+   :language: javascript
+
+
+
+
+
+
+
+
+
+
+
+
+

api-ref/source/databases.inc

@@ -0,0 +1,137 @@
+.. -*- rst -*-
+
+=====================
+Databases (databases)
+=====================
+
+Creates, lists all, and deletes databases.
+
+
+Delete database
+===============
+
+.. rest_method::  DELETE /v1.0/{accountId}/instances/{instanceId}/databases/{databaseName}
+
+Deletes a database.
+
+This operation also deletes all data that is associated with the
+database.
+
+Error response codes:202,413,405,404,403,401,400,422,503,500,501,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - instanceId: instanceId
+   - databaseName: databaseName
+   - accountId: accountId
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Create database
+===============
+
+.. rest_method::  POST /v1.0/{accountId}/instances/{instanceId}/databases
+
+Creates a database within an instance.
+
+The ``name`` of the database is a required attribute.
+
+Error response codes:202,413,405,404,403,401,400,422,503,500,501,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - characterSet: characterSet
+   - collate: collate
+   - name: name
+   - instanceId: instanceId
+   - accountId: accountId
+
+Request Example
+---------------
+
+.. literalinclude:: samples/db-create-databases-request.json
+   :language: javascript
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+List instance databases
+=======================
+
+.. rest_method::  GET /v1.0/{accountId}/instances/{instanceId}/databases
+
+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.
+
+
+Normal response codes: 200
+Error response codes:413,405,404,403,401,400,422,503,500,501,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - instanceId: instanceId
+   - accountId: accountId
+
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/db-list-databases-response.json
+   :language: javascript
+
+
+
+
+
+
+
+
+
+
+
+
+

api-ref/source/datastores.inc

@@ -0,0 +1,143 @@
+.. -*- rst -*-
+
+========================
+Data stores (datastores)
+========================
+
+Lists data store versions, lists parameters for data stores, and
+shows parameter details for a data store version.
+
+
+Show configuration parameter details
+====================================
+
+.. rest_method::  GET /v1.0/{accountId}/datastores/versions/{datastore_version_id}/parameters/{parameter_name}
+
+Displays details for a configuration parameter associated with a data store version.
+
+Details include the type, minimum and maximum values, and whether
+you must restart the instance after you change the parameter value.
+
+
+Normal response codes: 200
+Error response codes:413,405,404,403,401,400,422,503,500,501,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - parameter_name: parameter_name
+   - datastore_version_id: datastore_version_id
+   - accountId: accountId
+
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/db-show-parameter-details.json
+   :language: javascript
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+List datastore versions
+=======================
+
+.. rest_method::  GET /v1.0/{accountId}/datastores/{datastore_name}/versions
+
+Lists the available versions of a data store.
+
+
+Normal response codes: 200
+Error response codes:413,405,404,403,401,400,422,503,500,501,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - datastore_name: datastore_name
+   - accountId: accountId
+
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/db-list-datastore-versions.json
+   :language: javascript
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+List configuration parameters
+=============================
+
+.. rest_method::  GET /v1.0/{accountId}/datastores/versions/{datastore_version_id}/parameters
+
+Lists the available configuration parameters for a data store version.
+
+Parameter information includes the type, minimum and maximum
+values, and whether you must restart the instance after you change
+a parameter value.
+
+
+Normal response codes: 200
+Error response codes:413,405,404,403,401,400,422,503,500,501,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - datastore_version_id: datastore_version_id
+   - accountId: accountId
+
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/db-list-parameters-response.json
+   :language: javascript
+
+
+
+
+
+
+
+
+
+
+
+
+

api-ref/source/flavors.inc

@@ -0,0 +1,104 @@
+.. -*- rst -*-
+
+=================
+Flavors (flavors)
+=================
+
+Lists all flavors and shows details for a flavor, by ID.
+
+
+Show flavor details
+===================
+
+.. rest_method::  GET /v1.0/{accountId}/flavors/{flavorId}
+
+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 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.
+
+
+Normal response codes: 200
+Error response codes:413,405,404,403,401,400,422,503,500,501,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - flavorId: flavorId
+   - accountId: accountId
+
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/db-flavors-by-id-response.json
+   :language: javascript
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+List flavors
+============
+
+.. rest_method::  GET /v1.0/{accountId}/flavors
+
+Lists information for all available flavors.
+
+This operation lists information for all available flavors.
+
+This resource is identical to the flavors found in the OpenStack
+Nova API, but without the disk property.
+
+
+Normal response codes: 200
+Error response codes:413,405,404,403,401,400,422,503,500,501,
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - accountId: accountId
+
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/db-flavors-response.json
+   :language: javascript
+
+
+
+
+
+
+
+
+
+
+
+
+

api-ref/source/index.rst

@@ -0,0 +1,16 @@
+:tocdepth: 2
+
+===================
+ Database API
+===================
+
+.. rest_expand_all::
+
+.. include:: api-versions.inc
+.. include:: database-instances.inc
+.. include:: database-instance-actions.inc
+.. include:: databases.inc
+.. include:: user-management.inc
+.. include:: flavors.inc
+.. include:: datastores.inc
+.. include:: configurations.inc

api-ref/source/parameters.yaml

@@ -0,0 +1,286 @@
+# variables in path
+accountId:
+  description: |
+    The account ID of the owner of the instance.
+  in: path
+  required: false
+  type: string
+configId:
+  description: |
+    The ID of the configuration group.
+  in: path
+  required: false
+  type: string
+databaseName:
+  description: |
+    The name for the database.
+  in: path
+  required: false
+  type: string
+datastore_name:
+  description: |
+    The name of the data store.
+  in: path
+  required: false
+  type: string
+datastore_version_id:
+  description: |
+    The UUID of the data store version.
+  in: path
+  required: false
+  type: string
+flavorId:
+  description: |
+    The ID for the flavor.
+  in: path
+  required: false
+  type: string
+instanceId:
+  description: |
+    The ID for the database instance.
+  in: path
+  required: false
+  type: string
+parameter_name:
+  description: |
+    The name of the parameter for which to show
+    details.
+  in: path
+  required: false
+  type: string
+# variables in body
+characterSet:
+  description: |
+    A set of symbols and encodings. Default is
+    ``utf8``.  For information about supported character sets and
+    collations, see `Character Sets and Collations in MySQL
+    <http://dev.mysql.com/doc/refman/5.1/en/charset-mysql.html>`_.
+  in: body
+  required: false
+  type: string
+collate:
+  description: |
+    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 <http://dev.mysql.com/doc/refman/5.1/en
+    /charset-mysql.html>`_.
+  in: body
+  required: false
+  type: string
+configuration:
+  description: |
+    ID of the configuration group that you want to
+    attach to the instance.
+  in: body
+  required: true
+  type: string
+configuration_1:
+  description: |
+    ID of the configuration group to attach to the
+    instance.
+  in: body
+  required: false
+  type: string
+configuration_2:
+  description: |
+    To detach a configuration group, set the
+    configuration parameter to null.
+  in: body
+  required: true
+  type: string
+created:
+  description: |
+    The date and time when the resource was created.
+
+    The date and time stamp format is `ISO 8601
+    <https://en.wikipedia.org/wiki/ISO_8601>`_:
+
+    ::
+
+       CCYY-MM-DDThh:mm:ss±hh:mm
+
+    For example, ``2015-08-27T09:49:58-05:00``.
+
+    The ``±hh:mm`` value, if included, is the time zone as an offset
+    from UTC. In the previous example, the offset value is ``-05:00``.
+  in: body
+  required: true
+  type: string
+databases:
+  description: |
+    A ``databases`` object.
+  in: body
+  required: false
+  type: array
+datastore:
+  description: |
+    Data store assigned to the configuration group.
+    Required if you did not configure the default data store.
+  in: body
+  required: true
+  type: string
+datastore_1:
+  description: |
+    Name of the datastore to use when creating the
+    instance.
+  in: body
+  required: false
+  type: string
+datastore_version:
+  description: |
+    Name of the datastore version to use when
+    creating the instance.
+  in: body
+  required: false
+  type: string
+description:
+  description: |
+    New description of the configuration group.
+  in: body
+  required: true
+  type: string
+flavor:
+  description: |
+    A ``flavor`` object, which includes the flavor ID
+    (integer) and flavor relative links.
+  in: body
+  required: true
+  type: object
+flavorRef:
+  description: |
+    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``.
+  in: body
+  required: true
+  type: string
+instance:
+  description: |
+    An ``instance`` object.
+  in: body
+  required: true
+  type: object
+name:
+  description: |
+    Name of the configuration group you are creating.
+  in: body
+  required: true
+  type: string
+name_1:
+  description: |
+    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.
+  in: body
+  required: false
+  type: string
+name_2:
+  description: |
+    The user name for the database on instance
+    creation.
+  in: body
+  required: false
+  type: string
+name_3:
+  description: |
+    New name of the configuration group.
+  in: body
+  required: true
+  type: string
+password:
+  description: |
+    The password for those users on instance
+    creation.
+  in: body
+  required: false
+  type: string
+replica_count:
+  description: |
+    Number of replicas to create (defaults to 1).
+  in: body
+  required: false
+  type: integer
+replica_of:
+  description: |
+    ID or name of an existing instance to replicate
+    from.
+  in: body
+  required: false
+  type: string
+replica_of_1:
+  description: |
+    To detach a replica, set ``replica_of`` to null.
+  in: body
+  required: true
+  type: string
+size:
+  description: |
+    The volume size, in gigabytes (GB). A valid value
+    is from 1 to 50.
+  in: body
+  required: true
+  type: integer
+slave_of:
+  description: |
+    To detach a replica, set ``slave_of`` to null.
+  in: body
+  required: true
+  type: string
+type:
+  description: |
+    The volume type to use. You can list the
+    available volume types on your system by using the ``cinder type-
+    list`` command.  If you want to specify a volume type, you must
+    also specify a volume size.
+  in: body
+  required: false
+  type: string
+updated:
+  description: |
+    The date and time when the resource was updated.
+
+    The date and time stamp format is `ISO 8601
+    <https://en.wikipedia.org/wiki/ISO_8601>`_:
+
+    ::
+
+       CCYY-MM-DDThh:mm:ss±hh:mm
+
+    The ``±hh:mm`` value, if included, is the time zone as an offset
+    from UTC.
+
+    For example, ``2015-08-27T09:49:58-05:00``.
+
+    The UTC time zone is assumed.
+  in: body
+  required: true
+  type: string
+users:
+  description: |
+    A ``users`` object.
+  in: body
+  required: true
+  type: array
+values:
+  description: |
+    Dictionary that lists configuration parameter
+    names and associated values.
+  in: body
+  required: true
+  type: string
+values_1:
+  description: |
+    Dictionary that lists configuration parameter
+    names and associated values.
+  in: body
+  required: true
+  type: object
+

api-ref/source/samples/db-attach-config-group-request-json-http.txt

@@ -0,0 +1,7 @@
+PUT /v1.0/1234/instances/4c93c73b-d6d0-47d7-b8c6-b699d19d7de9 HTTP/1.1
+User-Agent: python-example-client
+Host: openstack.example.com
+X-Auth-Token: 87c6033c-9ff6-405f-943e-2deb73f278b7
+Accept: application/json
+Content-Type: application/json
+

api-ref/source/samples/db-attach-config-group-request.json

@@ -0,0 +1,5 @@
+{
+    "instance": {
+        "configuration": "2aa51628-5c42-4086-8682-137caffd2ba6"
+    }
+}

api-ref/source/samples/db-attach-config-group-response-json-http.txt

@@ -0,0 +1,5 @@
+HTTP/1.1 202 OK
+Content-Type: application/json
+Content-Length: 0
+Date: Mon, 13 Jul 2015 19:53:04 GMT
+

api-ref/source/samples/db-backup-create-incremental-request.json

@@ -6,4 +6,3 @@
         "parent_id": "a9832168-7541-4536-b8d9-a8a9b79cf1b4"
     }
 }
-

api-ref/source/samples/db-backup-create-incremental-response.json

@@ -17,4 +17,3 @@
         "updated": "2014-10-30T12:30:00"
     }
 }
-

api-ref/source/samples/db-backup-create-request.json

@@ -5,4 +5,3 @@
         "name": "snapshot"
     }
 }
-

api-ref/source/samples/db-backup-create-response.json

@@ -17,4 +17,3 @@
         "updated": "2014-10-30T12:30:00"
     }
 }
-

api-ref/source/samples/db-backup-get-response.json

@@ -17,4 +17,3 @@
         "updated": "2014-10-30T12:30:00"
     }
 }
-

api-ref/source/samples/db-backup-restore-request.json

@@ -10,4 +10,3 @@
         }
     }
 }
-

api-ref/source/samples/db-backup-restore-response.json

@@ -38,4 +38,3 @@
         }
     }
 }
-

api-ref/source/samples/db-change-user-attributes-request.json

@@ -4,4 +4,3 @@
         "password": "new_password"
     }
 }
-

api-ref/source/samples/db-check-root-user-response.json

@@ -1,4 +1,3 @@
 {
     "rootEnabled": true
 }
-

api-ref/source/samples/db-config-group-details-request-json-http.txt

@@ -0,0 +1,6 @@
+GET /v1.0/1234/configurations/5678 HTTP/1.1
+User-Agent: python-example-client
+Host: openstack.example.com
+X-Auth-Token: 87c6033c-9ff6-405f-943e-2deb73f278b7
+Accept: application/json
+Content-Type: application/json

api-ref/source/samples/db-config-group-details-response-json-http.txt

@@ -0,0 +1,4 @@
+HTTP/1.1 200 OK
+Content-Type: application/json
+Content-Length: 138
+Date: Fri, 20 Nov 2015 19:53:04 GMT

api-ref/source/samples/db-config-group-details-response.json

@@ -0,0 +1,16 @@
+{
+    "configuration": {
+        "datastore_name": "mysql",
+        "updated": "2015-11-22T19:07:20",
+        "values": {
+            "connect_timeout": 17
+        },
+        "name": "group1",
+        "created": "2015-11-20T20:51:24",
+        "datastore_version_name": "5.6",
+        "instance_count": 1,
+        "id": "1c8a4fdd-690c-4e6e-b2e1-148b8d738770",
+        "datastore_version_id": "b9f97132-467b-4f8e-b12d-947cfc223ac3",
+        "description": null
+    }
+}

api-ref/source/samples/db-config-group-instances-request-json-http.txt

@@ -0,0 +1,6 @@
+GET /v1.0/1234/configurations/5678/instances HTTP/1.1
+User-Agent: python-example-client
+Host: openstack.example.com
+X-Auth-Token: 87c6033c-9ff6-405f-943e-2deb73f278b7
+Accept: application/json
+Content-Type: application/json

api-ref/source/samples/db-config-group-instances-response-json-http.txt

@@ -0,0 +1,4 @@
+HTTP/1.1 200 OK
+Content-Type: application/json
+Content-Length: 138
+Date: Fri, 20 Nov 2015 19:53:04 GMT

api-ref/source/samples/db-config-group-instances-response.json

@@ -0,0 +1,8 @@
+{
+    "instances": [
+        {
+            "id": "7fd2d1d6-a2ef-4a76-8c03-e233db4d86da",
+            "name": "master_1"
+        }
+    ]
+}

api-ref/source/samples/db-configuration-attach-to-instance-request.json

@@ -3,4 +3,3 @@
         "configuration": "43a6ea86-e959-4735-9e46-a6a5d4a2d80f"
     }
 }
-

api-ref/source/samples/db-configuration-create-request.json

@@ -12,4 +12,3 @@
         }
     }
 }
-

api-ref/source/samples/db-configuration-create-response.json

@@ -15,4 +15,3 @@
         }
     }
 }
-

api-ref/source/samples/db-configuration-detach-from-instance-request.json

@@ -3,4 +3,3 @@
         "configuration": ""
     }
 }
-

api-ref/source/samples/db-configuration-details-response.json

@@ -15,4 +15,3 @@
         }
     }
 }
-

api-ref/source/samples/db-configuration-edit-parameters-request.json

@@ -5,4 +5,3 @@
         }
     }
 }
-

api-ref/source/samples/db-configuration-list-instances-response.json

@@ -6,4 +6,3 @@
         }
     ]
 }
-

api-ref/source/samples/db-configuration-list-response.json

@@ -12,4 +12,3 @@
         }
     ]
 }
-

api-ref/source/samples/db-configuration-update-parameters-request.json

@@ -8,4 +8,3 @@
         }
     }
 }
-

api-ref/source/samples/db-create-config-group-request-json-http.txt

@@ -0,0 +1,7 @@
+POST /v1.0/1234/configurations HTTP/1.1
+User-Agent: python-example-client
+Host: openstack.example.com
+X-Auth-Token: d6cafa5b-e0c7-4ab8-948e-7c95f2acd031
+Accept: application/json
+Content-Type: application/json
+

api-ref/source/samples/db-create-config-group-request.json

@@ -0,0 +1,15 @@
+{
+    "configuration": {
+        "datastore": [
+            {
+                "type": "mysql"
+            }
+        ],
+        "values": [
+            {
+                "sync_binlog": 1
+            }
+        ],
+        "name": "group1"
+    }
+}

api-ref/source/samples/db-create-config-group-response-json-http.txt

@@ -0,0 +1,5 @@
+HTTP/1.1 200 OK
+Content-Type: application/json
+Content-Length: 360
+Date: Mon, 6 Jul 2015 21:53:10 GMT
+

api-ref/source/samples/db-create-config-group-response.json

@@ -0,0 +1,14 @@
+{
+    "updated": "2015-07-01T16:38:27",
+    "name": "group1",
+    "created": "2015-07-01T16:38:27",
+    "instance_count": 0,
+    "values": {
+        "sync_binlog": 1
+    },
+    "datastore_version_id": "2dc7faa0-efff-4c2b-8cff-bcd949c518a5",
+    "id": "2aa51628-5c42-4086-8682-137caffd2ba6",
+    "datastore_name": "mysql",
+    "datastore_version_name": "5.6",
+    "description": null
+}

api-ref/source/samples/db-create-databases-request.json

@@ -13,4 +13,3 @@
         }
     ]
 }
-

api-ref/source/samples/db-create-instance-request.json

@@ -28,4 +28,3 @@
         }
     }
 }
-