Add protectables api-ref

add api reference of protectables.

Change-Id: I31673ce2c0c7f0f381c697256569e53be624dfda

api-ref/source/v1/index.rst

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

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

@@ -0,0 +1,189 @@
+.. -*- rst -*-
+
+============
+Protectables
+============
+
+Enables the Karbor user to access information about which resource types are
+protectable (i.e. can be protected by Karbor).  In addition, enables the user
+to get additional information on each resource type, such as a list of actual
+instances and their dependencies.
+
+
+List protectable types
+======================
+
+.. rest_method:: GET /v1/{tenant_id}/protectables
+
+Lists all the available protectable types.
+
+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
+   - protectable_type: protectable_type
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/protectables-list-response.json
+   :language: javascript
+
+
+Show protectable type
+=====================
+
+.. rest_method:: GET /v1/{tenant_id}/plans/{protectable_type}
+
+Shows the information of a given protectable type.
+
+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
+   - protectable_type: protectable_type_1
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+   - X-Openstack-Request-Id: request_id
+   - protectable_type: protectable_type_2
+   - name: protectable_name
+   - dependent_types: dependent_types
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/protectable-show-response.json
+   :language: javascript
+
+
+List protectable instances
+==========================
+
+.. rest_method:: GET /v1/{tenant_id}/plans/{protectable_type}/instances
+
+List all the available instances for the given protectable type.
+
+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
+   - protectable_type: protectable_type_1
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+   - X-Openstack-Request-Id: request_id
+   - instances: protectable_instance_list
+   - id: protectable_instance_id
+   - type: protectable_type_3
+   - name: protectable_instance_name
+   - dependent_resources: dependent_resources
+   - instances_links: links
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/protectable-instances-list-response.json
+   :language: javascript
+
+
+Show protectable instance
+=========================
+
+.. rest_method::  GET /v1/{tenant_id}/plans/{protectable_type}/instances/{resource_id}
+
+Show the information about a specific instance and its immediate dependencies.
+
+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
+   - protectable_type: protectable_type_1
+   - resource_id: resource_id
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+   - X-Openstack-Request-Id: request_id
+   - instance: protectable_instance
+   - id: protectable_instance_id
+   - type: protectable_type_3
+   - name: protectable_instance_name
+   - dependent_resources: dependent_resources
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/protectable-instance-show-response.json
+   :language: javascript

api-ref/source/v1/parameters.yaml

@@ -14,12 +14,24 @@ checkpoint_id_1:
   in: path
   required: true
   type: UUID
+protectable_type_1:
+  description: |
+    The name of a specified protectable type.
+  in: path
+  required: true
+  type: string
 provider_id_1:
   description: |
     The UUID of a provider.
   in: path
   required: true
   type: UUID
+resource_id:
+  description: |
+    The UUID of a resource.
+  in: path
+  required: true
+  type: UUID
 tenant_id:
   description: |
     The UUID of the tenant in a multi-tenancy cloud.
@@ -57,6 +69,19 @@ checkpoint_status:
   in: body
   required: true
   type: string
+dependent_resources:
+  description: |
+    All dependent resources for a given protectable instance, It can be an
+    empty list.
+  in: body
+  required: true
+  type: array
+dependent_types:
+  description: |
+    All dependent protectable type, It can be an empty list.
+  in: body
+  required: true
+  type: array
 links:
   description: |
     Links for transfer.
@@ -111,6 +136,54 @@ plan_status_1:
   in: body
   required: false
   type: string
+protectable_instance:
+  description: |
+    A ``protectable_instance`` object.
+  in: body
+  required: true
+  type: object
+protectable_instance_id:
+  description: |
+    The UUID of a protectable instance.
+  in: body
+  required: true
+  type: UUID
+protectable_instance_list:
+  description: |
+    The list of ``protectable_instance`` objects.
+  in: body
+  required: true
+  type: array
+protectable_instance_name:
+  description: |
+    The name of a protectable instance.
+  in: body
+  required: true
+  type: string
+protectable_name:
+  description: |
+    The name of the protectable type.
+  in: body
+  required: true
+  type: string
+protectable_type:
+  description: |
+    All the available protection types.
+  in: body
+  required: true
+  type: array
+protectable_type_2:
+  description: |
+    A ``protectable_type`` object.
+  in: body
+  required: true
+  type: object
+protectable_type_3:
+  description: |
+    The name of a specified protectable type.
+  in: body
+  required: true
+  type: string
 provider_id:
   description: |
     The UUID of the provider.

api-ref/source/v1/samples/protectable-instance-show-response.json

@@ -0,0 +1,14 @@
+{
+  "instance": {
+    "id": "cb4ef2ff-10f5-46c9-bce4-cf7a49c65a01",
+    "type": "OS::Nova::Server",
+    "name": "My VM",
+    "dependent_resources": [
+      {
+        "id": "99777fdd-8a5b-45ab-ba2c-52420008103f",
+        "type": "OS::Glance::Image",
+        "name": "cirros-0.3.4-x86_64-uec"
+      }
+    ]
+  }
+}

api-ref/source/v1/samples/protectable-instances-list-response.json

@@ -0,0 +1,22 @@
+{
+  "instances": [
+    {
+      "id": "cb4ef2ff-10f5-46c9-bce4-cf7a49c65a01",
+      "type": "OS::Nova::Server",
+      "name": "My VM",
+      "dependent_resources": [
+        {
+          "id": "99777fdd-8a5b-45ab-ba2c-52420008103f",
+          "type": "OS::Glance::Image",
+          "name": "cirros-0.3.4-x86_64-uec"
+        }
+      ]
+    }
+  ],
+  "instances_links": [
+    {
+      "href": "/v1/{project_id}/instances?limit=1&marker=cb4ef2ff-10f5-46c9-bce4-cf7a49c65a01",
+      "rel": "next"
+    }
+  ]
+}

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

@@ -0,0 +1,9 @@
+{
+  "protectable_type": {
+    "name": "OS::Nova::Server",
+    "dependent_types": [
+      "OS::Cinder::Volume",
+      "OS::Glance::Image"
+    ]
+  }
+}

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

@@ -0,0 +1,8 @@
+{
+  "protectable_type": [
+    "OS::Keystone::Project",
+    "OS::Cinder::Volume",
+    "OS::Glance::Image",
+    "OS::Nova::Server"
+  ]
+}