Add providers api-ref

add api reference of providers.

Change-Id: I9ad0bed7dce6d24f7a5bcdcd1343a4566525b16a

api-ref/source/v1/index.rst

@@ -7,5 +7,6 @@ Data Protection API V1
 .. rest_expand_all::
 
 .. include:: karbor-v1-protectables.inc
+.. include:: karbor-v1-providers.inc
 .. include:: karbor-v1-plans.inc
 .. include:: karbor-v1-checkpoints.inc

api-ref/source/v1/karbor-v1-providers.inc

@@ -0,0 +1,106 @@
+.. -*- rst -*-
+
+=========
+Providers
+=========
+
+Enables the Karbor user to list available providers and get parameters and
+result schema super-set for all plugins of a specific Provider.
+
+
+List protection providers
+=========================
+
+.. rest_method:: GET /v1/{tenant_id}/providers
+
+List all the information about the providers offered at a given service, or
+part of the providers limited by ``?limit={limit_num}`` by ``GET`` method.
+All providers need to be configured first by the admin.
+
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 401
+   - 403
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - tenant_id: tenant_id
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+   - X-Openstack-Request-Id: request_id
+   - providers: provider_list
+   - id: provider_id
+   - name: provider_name
+   - description: description
+   - extended_info_schema: schema_extended_info
+   - saved_info_schema: schema_saved_info
+   - restore_schema: schema_restore
+   - providers_links: links
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/providers-list-response.json
+   :language: javascript
+
+
+Show protection provider
+========================
+
+.. rest_method:: GET /v1/{tenant_id}/providers/{provider_id}
+
+Shows the information about a specific provider.
+
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 401
+   - 403
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - tenant_id: tenant_id
+   - provider_id: provider_id_1
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+   - X-Openstack-Request-Id: request_id
+   - provider: provider
+   - id: provider_id
+   - name: provider_name
+   - description: description
+   - extended_info_schema: schema_extended_info
+   - saved_info_schema: schema_saved_info
+   - restore_schema: schema_restore
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/provider-show-response.json
+   :language: javascript

api-ref/source/v1/parameters.yaml

@@ -82,6 +82,13 @@ dependent_types:
   in: body
   required: true
   type: array
+description:
+  description: |
+    The description for this object, resource, operation and so on. May be
+    ``NULL``.
+  in: body
+  required: true
+  type: string
 links:
   description: |
     Links for transfer.
@@ -184,12 +191,30 @@ protectable_type_3:
   in: body
   required: true
   type: string
+provider:
+  description: |
+    A ``provider`` object.
+  in: body
+  required: true
+  type: object
 provider_id:
   description: |
     The UUID of the provider.
   in: body
   required: true
   type: UUID
+provider_list:
+  description: |
+    The list of ``provider`` objects.
+  in: body
+  required: true
+  type: array
+provider_name:
+  description: |
+    The name of the provider.
+  in: body
+  required: true
+  type: string
 resource_graph:
   description: |
     The resource graph of protection plan corresponding to the checkpoint.
@@ -208,6 +233,24 @@ resources_1:
   in: body
   required: false
   type: array
+schema_extended_info:
+  description: |
+    The extended info schema for provider.
+  in: body
+  required: true
+  type: dict
+schema_restore:
+  description: |
+    The restore schema for provider.
+  in: body
+  required: true
+  type: dict
+schema_saved_info:
+  description: |
+    The saved info schema for provider.
+  in: body
+  required: true
+  type: dict
 tenant_id_1:
   description: |
     The UUID of the tenant in a multi-tenancy cloud.

api-ref/source/v1/samples/provider-show-response.json

@@ -0,0 +1,60 @@
+{
+  "provider": {
+    "id": "2220f8b1-975d-4621-a872-fa9afb43cb6c",
+    "name": "OS Infra Provider",
+    "description": "This provider uses OpenStack's own services (swift, cinder) as storage",
+    "extended_info_schema": {
+      "options_schema": {
+        "OS::Cinder::Volume": {
+          "required": [
+            "backup_mode"
+          ],
+          "type": "object",
+          "properties": {
+            "backup_mode": {
+              "default": "auto",
+              "enum": [
+                "full",
+                "incremental",
+                "auto"
+              ],
+              "type": "string",
+              "description": "The backup mode.",
+              "title": "Backup Mode"
+            }
+          },
+          "title": "Cinder Protection Options"
+        }
+      },
+      "saved_info_schema": {
+        "OS::Cinder::Volume": {
+          "required": [
+            "name"
+          ],
+          "type": "object",
+          "properties": {
+            "name": {
+              "type": "string",
+              "description": "The name for this backup.",
+              "title": "Name"
+            }
+          },
+          "title": "Cinder Protection Saved Info"
+        }
+      },
+      "restore_schema": {
+        "OS::Cinder::Volume": {
+          "type": "object",
+          "properties": {
+            "restore_name": {
+              "type": "string",
+              "description": "The name of the restored volume.",
+              "title": "Restore Name"
+            }
+          },
+          "title": "Cinder Protection Restore"
+        }
+      }
+    }
+  }
+}

api-ref/source/v1/samples/providers-list-response.json

@@ -0,0 +1,68 @@
+{
+  "providers": [
+    {
+      "id": "2220f8b1-975d-4621-a872-fa9afb43cb6c",
+      "name": "OS Infra Provider",
+      "description": "This provider uses OpenStack's own services (swift, cinder) as storage",
+      "extended_info_schema": {
+        "options_schema": {
+          "OS::Cinder::Volume": {
+            "required": [
+              "backup_mode"
+            ],
+            "type": "object",
+            "properties": {
+              "backup_mode": {
+                "default": "auto",
+                "enum": [
+                  "full",
+                  "incremental",
+                  "auto"
+                ],
+                "type": "string",
+                "description": "The backup mode.",
+                "title": "Backup Mode"
+              }
+            },
+            "title": "Cinder Protection Options"
+          }
+        },
+        "saved_info_schema": {
+          "OS::Cinder::Volume": {
+            "required": [
+              "name"
+            ],
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string",
+                "description": "The name for this backup.",
+                "title": "Name"
+              }
+            },
+            "title": "Cinder Protection Saved Info"
+          }
+        },
+        "restore_schema": {
+          "OS::Cinder::Volume": {
+            "type": "object",
+            "properties": {
+              "restore_name": {
+                "type": "string",
+                "description": "The name of the restored volume.",
+                "title": "Restore Name"
+              }
+            },
+            "title": "Cinder Protection Restore"
+          }
+        }
+      }
+    }
+  ],
+  "providers_links": [
+    {
+      "href": "/v1/{project_id}/providers?limit={limit_num}&marker=cf56bd3e-97a7-4078-b6d5-f36246333fd9",
+      "rel": "next"
+    }
+  ]
+}