Improve API doc

Change-Id: If48ef016c6fb7a875ceabc9f106e4cd85858d147

1 files changed, 110 insertions, 45 deletions

diff --git a/api-ref/source/databases.inc b/api-ref/source/databases.inc
index aaf60a1c..c7c1df77 100644
--- a/api-ref/source/databases.inc
+++ b/api-ref/source/databases.inc
@@ -1,53 +1,83 @@
 .. -*- rst -*-
 
-=====================
-Databases (databases)
-=====================
+=========
+Databases
+=========
 
-Creates, lists all, and deletes databases.
 
 
-Delete database
-~~~~~~~~~~~~~~~
 
-.. rest_method::  DELETE /v1.0/{project_id}/instances/{instanceId}/databases/{databaseName}
+Create database
+~~~~~~~~~~~~~~~
 
-Deletes a database.
+.. rest_method::  POST /v1.0/{project_id}/instances/{instanceId}/databases
 
-This operation also deletes all data that is associated with the
-database.
+Creates a database within an instance.
 
 Normal response codes: 202
 
-Error response codes: badRequest(400), unauthorized(401), forbidden(403),
-itemNotFound(404), badMethod(405), overLimit(413), unprocessableEntity(422),
-instanceFault(500), notImplemented(501), serviceUnavailable(503)
-
 
 Request
 -------
 
 .. rest_parameters:: parameters.yaml
 
+   - project_id: project_id
    - instanceId: instanceId
-   - databaseName: databaseName
+   - name: name
+   - characterSet: characterSet
+   - collate: collate
+
+
+Request Example
+---------------
+
+.. literalinclude:: samples/databases-create-request.json
+   :language: javascript
+
+
+
+
+List instance databases
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  GET /v1.0/{project_id}/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 get system databases such as
+``mysql``, ``information_schema``, and ``lost+found``.
+
+Normal response codes: 200
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
    - project_id: project_id
+   - instanceId: instanceId
+
 
+Response Example
+----------------
 
+.. literalinclude:: samples/databases-list-response.json
+   :language: javascript
 
 
-Create database
-~~~~~~~~~~~~~~~
 
-.. rest_method::  POST /v1.0/{project_id}/instances/{instanceId}/databases
 
-Creates a database within an instance.
+List instance databases for a user
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Normal response codes: 202
+.. rest_method::  GET /v1.0/{project_id}/instances/{instanceId}/users/{user_name}/databases
+
+Get all the databases that the user has access to.
 
-Error response codes: badRequest(400), unauthorized(401), forbidden(403),
-itemNotFound(404), badMethod(405), overLimit(413), unprocessableEntity(422),
-instanceFault(500), notImplemented(501), serviceUnavailable(503)
+Normal response codes: 200
 
 
 Request
@@ -55,39 +85,57 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-   - characterSet: characterSet
-   - collate: collate
-   - name: name
+   - project_id: project_id
    - instanceId: instanceId
+   - user_name: user_name
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/databases-list-response.json
+   :language: javascript
+
+
+
+
+Grant databases access
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  PUT /v1.0/{project_id}/instances/{instanceId}/users/{user_name}/databases
+
+Grant user access to the databases.
+
+Normal response codes: 202
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
    - project_id: project_id
+   - instanceId: instanceId
+   - user_name: user_name
 
 
 Request Example
 ---------------
 
-.. literalinclude:: samples/db-create-databases-request.json
+.. literalinclude:: samples/user-grant-databases-access-request.json
    :language: javascript
 
 
 
 
-List instance databases
+Revoke databases access
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-.. rest_method::  GET /v1.0/{project_id}/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.
+.. rest_method::  DELETE /v1.0/{project_id}/instances/{instanceId}/users/{user_name}/databases/{database_name}
 
-Normal response codes: 200
+Revoke user access to the database.
 
-Error response codes: badRequest(400), unauthorized(401), forbidden(403),
-itemNotFound(404), badMethod(405), overLimit(413), unprocessableEntity(422),
-instanceFault(500), notImplemented(501), serviceUnavailable(503)
+Normal response codes: 202
 
 
 Request
@@ -95,12 +143,29 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-   - instanceId: instanceId
    - project_id: project_id
+   - instanceId: instanceId
+   - user_name: user_name
+   - database_name: databaseName
 
 
-Response Example
-----------------
 
-.. literalinclude:: samples/db-list-databases-response.json
-   :language: javascript
+
+Delete database
+~~~~~~~~~~~~~~~
+
+.. rest_method::  DELETE /v1.0/{project_id}/instances/{instanceId}/databases/{database_name}
+
+Deletes a database.
+
+Normal response codes: 202
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id
+   - instanceId: instanceId
+   - database_name: databaseName
\ No newline at end of file