[api-ref] Add sections for backups.

Change-Id: If3a929e9de31dd901c4838e85f91f76941f33d05
Closes-bug: #1663096
Signed-off-by: Fan Zhang <zh.f@outlook.com>

3 files changed, 341 insertions, 0 deletions

diff --git a/api-ref/source/backups.inc b/api-ref/source/backups.inc
new file mode 100644
index 00000000..9fb4f460
--- /dev/null
+++ b/api-ref/source/backups.inc
@@ -0,0 +1,254 @@
+.. -*- rst -*-
+
+=======
+Backups
+=======
+
+List, show details, create and delete backups.
+
+
+List database backups
+~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  GET /v1.0/{accountId}/backups
+
+List all database backups information for a tenant.
+
+Normal response codes: 200
+
+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
+
+   - accountId: accountId
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+    - backups: backup_list
+    - created: created
+    - datastore: datastore2
+    - datastore.type: datastore_type1
+    - datastore.version: datastore_version_name
+    - datastore.version_id: datastore_version_id1
+    - description: backup_description1
+    - id: backup_id
+    - instance_id: backup_instanceId
+    - locationRef: backup_locationRef
+    - name: backup_name
+    - parent_id: backup_parentId1
+    - size: backup_size
+    - status: backup_status
+    - updated: updated
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/db-backup-list-response.json
+   :language: javascript
+
+
+
+
+List database backups for an instance
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  GET /v1.0/{accountId}/instances/{instanceId}/backups
+
+List all database backups for the specified instance.
+
+Normal response codes: 200
+
+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
+
+   - instanceId: instanceId
+   - accountId: accountId
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+    - backups: backup_list
+    - created: created
+    - datastore: datastore2
+    - datastore.type: datastore_type1
+    - datastore.version: datastore_version_name
+    - datastore.version_id: datastore_version_id1
+    - description: backup_description1
+    - id: backup_id
+    - instance_id: backup_instanceId
+    - locationRef: backup_locationRef
+    - name: backup_name
+    - parent_id: backup_parentId1
+    - size: backup_size
+    - status: backup_status
+    - updated: updated
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/db-backups-by-instance-response.json
+   :language: javascript
+
+
+
+
+Show database backup details
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  GET /v1.0/{accountId}/backups/{backupId}
+
+Show detailes of a backup.
+
+Normal response codes: 200
+
+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
+
+   - accountId: accountId
+   - backupId: backup_id
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+    - created: created
+    - datastore: datastore2
+    - datastore.type: datastore_type1
+    - datastore.version: datastore_version_name
+    - datastore.version_id: datastore_version_id1
+    - description: backup_description1
+    - id: backup_id
+    - instance_id: backup_instanceId
+    - locationRef: backup_locationRef
+    - name: backup_name
+    - parent_id: backup_parentId1
+    - size: backup_size
+    - status: backup_status
+    - updated: updated
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/db-backup-get-response.json
+   :language: javascript
+
+
+
+
+Create database backup
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  POST /v1.0/{accountId}/backups
+
+Creates a database backup for 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
+
+   - name: backup_name
+   - instance: backup_instanceId
+   - parent_id: backup_parentId
+   - incremental: backup_incremental
+   - description: backup_description
+   - accountId: accountId
+
+
+Request Example
+---------------
+
+.. literalinclude:: samples/db-backup-create-request.json
+   :language: javascript
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+    - created: created
+    - datastore: datastore2
+    - datastore.type: datastore_type1
+    - datastore.version: datastore_version_name
+    - datastore.version_id: datastore_version_id1
+    - description: backup_description1
+    - id: backup_id
+    - instance_id: backup_instanceId
+    - locationRef: backup_locationRef
+    - name: backup_name
+    - parent_id: backup_parentId1
+    - size: backup_size
+    - status: backup_status
+    - updated: updated
+
+
+Response Example
+----------------
+
+.. literalinclude:: samples/db-backup-create-response.json
+   :language: javascript
+
+
+
+
+Delete database backup
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  DELETE /v1.0/{accountId}/backups/{backupId}
+
+Deletes a database backup.
+
+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
+
+   - backupId: backup_id
+   - accountId: accountId
diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst
index d5cf2f4f..273dac4c 100755
--- a/api-ref/source/index.rst
+++ b/api-ref/source/index.rst
@@ -15,3 +15,4 @@
 .. include:: flavors.inc
 .. include:: datastores.inc
 .. include:: configurations.inc
+.. include:: backups.inc
diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index 0c3ff53b..ecd75b76 100755
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -5,6 +5,12 @@ accountId:
   in: path
   required: false
   type: string
+backup_id:
+  description: |
+    The ID of the backup.
+  in: path
+  required: true
+  type: string
 configId:
   description: |
     The ID of the configuration group.
@@ -61,6 +67,74 @@ availability_zone:
   in: body
   required: false
   type: string
+backup_description:
+  description: |
+    An optional description for the backup.
+  in: body
+  required: false
+  type: string
+backup_description1:
+  description: |
+    An optional description for the backup.
+  in: body
+  required: true
+  type: string
+backup_incremental:
+  description: |
+    Create an incremental backup based on the last full backup by setting this
+    parameter to 1 or 0. It will create a full backup if no existing backup
+    found.
+  in: body
+  required: false
+  type: integer
+backup_instanceId:
+  description: |
+    The ID of the instance to create backup for.
+  in: body
+  required: true
+  type: string
+backup_list:
+  description: |
+    A list of ``backup`` objects.
+  in: body
+  required: true
+  type: array
+backup_locationRef:
+  description: |
+    The URL of the backup location.
+  in: body
+  required: true
+  type: string
+backup_name:
+  description: |
+    Name of the backup.
+  in: body
+  required: true
+  type: string
+backup_parentId:
+  description: |
+    ID of the parent backup to perform an incremental backup from.
+  in: body
+  required: false
+  type: string
+backup_parentId1:
+  description: |
+    ID of the parent backup to perform an incremental backup from.
+  in: body
+  required: true
+  type: string
+backup_size:
+  description: |
+    Size of the backup, the unit is GB.
+  in: body
+  required: true
+  type: string
+backup_status:
+  description: |
+    Status of the backup.
+  in: body
+  required: true
+  type: string
 characterSet:
   description: |
     A set of symbols and encodings. Default is
@@ -203,6 +277,18 @@ datastore_version1:
   in: body
   required: true
   type: string
+datastore_version_id1:
+  description: |
+    The UUID of the data store version.
+  in: body
+  required: true
+  type: string
+datastore_version_name:
+  description: |
+    The name of the datastore version.
+  in: body
+  required: true
+  type: string
 description:
   description: |
     New description of the configuration group.