Add api definition doc for operation log RESTful API

Change-Id: I2d749adbdca807436ea3dbc1b9c63fa0211a603a
blueprint: operation-log-api

api-ref/source/v1/index.rst

@@ -13,3 +13,4 @@ Data Protection API V1
 .. include:: karbor-v1-scheduled-operations.inc
 .. include:: karbor-v1-checkpoints.inc
 .. include:: karbor-v1-restores.inc
+.. include:: karbor-v1-operation-logs.inc

api-ref/source/v1/karbor-v1-operation-logs.inc

@@ -0,0 +1,136 @@
+.. -*- rst -*-
+
+==============
+Operation logs
+==============
+
+This API enables the Karbor user get the information about operation logs:
+
+-  List all operation logs by a given project.
+-  Show the information of a given operation log.
+
+When you perform the above operation, these status values are possible:
+
++-----------------+----------------------------------------------------------+
+| Status          | Description                                              |
++=================+==========================================================+
+| available       | A protect operation is finished.                         |
++-----------------+----------------------------------------------------------+
+| success         | A restore operation is success.                          |
++-----------------+----------------------------------------------------------+
+| deleted         | A delete operation is finished.                          |
++-----------------+----------------------------------------------------------+
+
+
+List operation logs
+===================
+
+.. rest_method:: GET /v1/{tenant_id}/operation_logs
+
+List all operation logs, triggered by a given project, or part of the operation
+logs limited by ``?limit={limit_num}`` by ``GET`` method.
+
+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
+   - sort: sort
+   - limit: limit
+   - marker: marker
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+   - X-Openstack-Request-Id: request_id
+   - operation_logs: operation_log_list
+   - id: operation_log_id
+   - project_id: tenant_id_1
+   - operation_type: operation_type
+   - checkpoint_id: checkpoint_id_2
+   - plan_id: plan_id_1
+   - provider_id: provider_id_2
+   - restore_id: restore_id_2
+   - scheduled_operation_id: operation_id_2
+   - status: operation_log_status
+   - started_at: started_at
+   - ended_at: ended_at
+   - error_info: error_info
+   - extra_info: extra_info
+   - operation_logs_links: links
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/operation-logs-list-response.json
+   :language: javascript
+
+
+Show operation log
+==================
+
+.. rest_method:: GET /v1/{tenant_id}/operation_logs/{operation_log_id}
+
+Show the information of a given operation log.
+
+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
+   - operation_log_id: operation_log_id_1
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+   - X-Openstack-Request-Id: request_id
+   - operation_log: operation_log
+   - id: operation_log_id
+   - project_id: tenant_id_1
+   - operation_type: operation_type_1
+   - checkpoint_id: checkpoint_id_2
+   - plan_id: plan_id_1
+   - provider_id: provider_id_2
+   - restore_id: restore_id_2
+   - scheduled_operation_id: operation_id_2
+   - status: operation_log_status
+   - started_at: started_at
+   - ended_at: ended_at
+   - error_info: error_info
+   - extra_info: extra_info_1
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/operation-log-show-response.json
+   :language: javascript

api-ref/source/v1/parameters.yaml

@@ -20,6 +20,12 @@ operation_id_1:
   in: path
   required: true
   type: UUID
+operation_log_id_1:
+  description: |
+    The UUID of the operation log.
+  in: path
+  required: true
+  type: UUID
 protectable_type_1:
   description: |
     The name of a specified protectable type.
@@ -101,6 +107,12 @@ checkpoint_id:
   in: body
   required: true
   type: UUID
+checkpoint_id_2:
+  description: |
+    The UUID of the checkpoint.
+  in: body
+  required: false
+  type: UUID
 checkpoint_list:
   description: |
     The list of ``checkpoint`` objects.
@@ -140,12 +152,30 @@ enabled:
   in: body
   required: true
   type: int
+ended_at:
+  description: |
+    The ended time of the operation.
+  in: body
+  required: false
+  type: string
+error_info:
+  description: |
+    The error info of of the operation.
+  in: body
+  required: false
+  type: dict
 extra_info:
   description: |
     The extra information for checkpoint.
   in: body
   required: false
   type: dict
+extra_info_1:
+  description: |
+    The extra info of of the operation.
+  in: body
+  required: false
+  type: dict
 links:
   description: |
     Links for transfer.
@@ -171,12 +201,42 @@ operation_id:
   in: body
   required: true
   type: UUID
+operation_id_2:
+  description: |
+    The UUID of the scheduled operation.
+  in: body
+  required: false
+  type: UUID
 operation_list:
   description: |
     The list of ``scheduled operation`` objects.
   in: body
   required: true
   type: array
+operation_log:
+  description: |
+    A ``operation_log`` object.
+  in: body
+  required: true
+  type: object
+operation_log_id:
+  description: |
+    The UUID of the operation_log.
+  in: body
+  required: true
+  type: UUID
+operation_log_list:
+  description: |
+    The list of ``operation_log`` objects.
+  in: body
+  required: true
+  type: array
+operation_log_status:
+  description: |
+    The status of operation logs.
+  in: body
+  required: false
+  type: string
 operation_name:
   description: |
     The name of the scheduled operation.
@@ -189,6 +249,12 @@ operation_type:
   in: body
   required: true
   type: string
+operation_type_1:
+  description: |
+    The type of the operation acitons.
+  in: body
+  required: true
+  type: UUID
 plan:
   description: |
     A ``plan`` object.
@@ -201,6 +267,12 @@ plan_id:
   in: body
   required: true
   type: UUID
+plan_id_1:
+  description: |
+    The UUID of the plan.
+  in: body
+  required: false
+  type: UUID
 plan_list:
   description: |
     The list of ``plan`` objects.
@@ -297,6 +369,12 @@ provider_id:
   in: body
   required: true
   type: UUID
+provider_id_2:
+  description: |
+    The UUID of the provider.
+  in: body
+  required: false
+  type: UUID
 provider_list:
   description: |
     The list of ``provider`` objects.
@@ -346,6 +424,12 @@ restore_id:
   in: body
   required: true
   type: UUID
+restore_id_2:
+  description: |
+    The UUID of the restore.
+  in: body
+  required: false
+  type: UUID
 restore_list:
   description: |
     The list of ``restore`` objects.
@@ -402,6 +486,12 @@ schema_saved_info:
   in: body
   required: true
   type: dict
+started_at:
+  description: |
+    The started time of the operation.
+  in: body
+  required: false
+  type: string
 tenant_id_1:
   description: |
     The UUID of the tenant in a multi-tenancy cloud.

api-ref/source/v1/samples/operation-log-show-response.json

@@ -0,0 +1,16 @@
+{
+    "operation_log": {
+        "status": "available",
+        "provider_id": "cf56bd3e-97a7-4078-b6d5-f36246333fd9",
+        "restore_id": null,
+        "checkpoint_id": "dbc459ff-2ac6-44fa-ba15-89350d7ebd43",
+        "error_info": null,
+        "ended_at": "2017-07-28T08:43:22.000000",
+        "started_at": "2017-07-28T08:42:02.000000",
+        "id": "7a16c731-0658-47dd-aa3b-98ee21830e23",
+        "extra_info": null,
+        "plan_id": "d58ffd3e-f64e-4b67-9bb0-b86d3483e7d0",
+        "scheduled_operation_id": null,
+        "operation_type": "protect"
+    }
+}

api-ref/source/v1/samples/operation-logs-list-response.json

@@ -0,0 +1,48 @@
+{
+    "operation_logs": [{
+        "status": "deleted",
+        "provider_id": "cf56bd3e-97a7-4078-b6d5-f36246333fd9",
+        "restore_id": null,
+        "checkpoint_id": "dbc459ff-2ac6-44fa-ba15-89350d7ebd43",
+        "error_info": null,
+        "ended_at": "2017-07-28T09:02:57.000000",
+        "started_at": "2017-07-28T09:02:41.000000",
+        "id": "f0aa664b-f385-4618-bc27-9e0116cceea7",
+        "extra_info": null,
+        "plan_id": "d58ffd3e-f64e-4b67-9bb0-b86d3483e7d0",
+        "scheduled_operation_id": null,
+        "operation_type": "protect"
+    },
+    {
+        "status": "success",
+        "provider_id": "cf56bd3e-97a7-4078-b6d5-f36246333fd9",
+        "restore_id": "7c0d396a-981b-4953-95f5-30382ddaa8bf",
+        "checkpoint_id": "dbc459ff-2ac6-44fa-ba15-89350d7ebd43",
+        "error_info": null,
+        "ended_at": "2017-07-28T08:58:08.000000",
+        "started_at": "2017-07-28T08:57:36.000000",
+        "id": "8736649d-857e-4637-923c-3bdb35edd74e",
+        "extra_info": null,
+        "plan_id": null,
+        "scheduled_operation_id": null,
+        "operation_type": "restore"
+    },
+    {
+        "status": "available",
+        "provider_id": "cf56bd3e-97a7-4078-b6d5-f36246333fd9",
+        "restore_id": null,
+        "checkpoint_id": "dbc459ff-2ac6-44fa-ba15-89350d7ebd43",
+        "error_info": null,
+        "ended_at": "2017-07-28T08:43:22.000000",
+        "started_at": "2017-07-28T08:42:02.000000",
+        "id": "7a16c731-0658-47dd-aa3b-98ee21830e23",
+        "extra_info": null,
+        "plan_id": "d58ffd3e-f64e-4b67-9bb0-b86d3483e7d0",
+        "scheduled_operation_id": null,
+        "operation_type": "protect"
+    }],
+    "operation_logs_links": [{
+        "href": "/v1/{project_id}/operation_logs?limit={limit_num}&marker=7a16c731-0658-47dd-aa3b-98ee21830e23",
+        "rel": "next"
+    }]
+}

doc/source/specs/api/api_examples.md

@@ -999,3 +999,81 @@ None
 ```json
 None
 ```
+
+----------
+
+## Operation_logs ##
+
+### List Operation_logs ###
+> **get** : /v1/{project_id}/operation_logs
+#### Response JSON ####
+```json
+{
+    "operation_logs": [{
+        "status": "deleted",
+        "provider_id": "cf56bd3e-97a7-4078-b6d5-f36246333fd9",
+        "restore_id": null,
+        "checkpoint_id": "dbc459ff-2ac6-44fa-ba15-89350d7ebd43",
+        "error_info": null,
+        "ended_at": "2017-07-28T09:02:57.000000",
+        "started_at": "2017-07-28T09:02:41.000000",
+        "id": "f0aa664b-f385-4618-bc27-9e0116cceea7",
+        "extra_info": null,
+        "plan_id": "d58ffd3e-f64e-4b67-9bb0-b86d3483e7d0",
+        "scheduled_operation_id": null,
+        "operation_type": "protect"
+    },
+    {
+        "status": "success",
+        "provider_id": "cf56bd3e-97a7-4078-b6d5-f36246333fd9",
+        "restore_id": "7c0d396a-981b-4953-95f5-30382ddaa8bf",
+        "checkpoint_id": "dbc459ff-2ac6-44fa-ba15-89350d7ebd43",
+        "error_info": null,
+        "ended_at": "2017-07-28T08:58:08.000000",
+        "started_at": "2017-07-28T08:57:36.000000",
+        "id": "8736649d-857e-4637-923c-3bdb35edd74e",
+        "extra_info": null,
+        "plan_id": null,
+        "scheduled_operation_id": null,
+        "operation_type": "restore"
+    },
+    {
+        "status": "available",
+        "provider_id": "cf56bd3e-97a7-4078-b6d5-f36246333fd9",
+        "restore_id": null,
+        "checkpoint_id": "dbc459ff-2ac6-44fa-ba15-89350d7ebd43",
+        "error_info": null,
+        "ended_at": "2017-07-28T08:43:22.000000",
+        "started_at": "2017-07-28T08:42:02.000000",
+        "id": "7a16c731-0658-47dd-aa3b-98ee21830e23",
+        "extra_info": null,
+        "plan_id": "d58ffd3e-f64e-4b67-9bb0-b86d3483e7d0",
+        "scheduled_operation_id": null,
+        "operation_type": "protect"
+    }]
+}
+```
+
+### Show operation_logs ###
+> **get** : /v1/{project_id}/operation_logs/{operation_log_id}
+#### Response JSON ####
+```json
+{
+    "operation_log": {
+        "status": "available",
+        "provider_id": "cf56bd3e-97a7-4078-b6d5-f36246333fd9",
+        "restore_id": null,
+        "checkpoint_id": "dbc459ff-2ac6-44fa-ba15-89350d7ebd43",
+        "error_info": null,
+        "ended_at": "2017-07-28T08:43:22.000000",
+        "started_at": "2017-07-28T08:42:02.000000",
+        "id": "7a16c731-0658-47dd-aa3b-98ee21830e23",
+        "extra_info": null,
+        "plan_id": "d58ffd3e-f64e-4b67-9bb0-b86d3483e7d0",
+        "scheduled_operation_id": null,
+        "operation_type": "protect"
+    }
+}
+```
+
+----------

doc/source/specs/api/karbor_api.v1.yaml

@@ -1011,15 +1011,16 @@ paths:
 
   /{project_id}/operation_logs/:
     get:
-      summary: Operation log entry point.
+      summary: Operation log.
       description: |
-        Get the information about operation instances in karbor.
+        Get the operation logs information about different operations(protect, delete, restore)
-        Whenever an operation is run a log instance is created.
+        in karbor protection service.
-        The user never creates operation logs.
-        This should not include the 'entires' property for the operation log.
       parameters:
         - $ref: '#/parameters/projectParam'
-        - $ref: '#/parameters/nameFilterParam'
+        - $ref: '#/parameters/checkpoint_idFilterParam'
+        - $ref: '#/parameters/plan_idFilterParam'
+        - $ref: '#/parameters/restore_idFilterParam'
+        - $ref: '#/parameters/statusFilterParam'
         - $ref: '#/parameters/sortParam'
         - $ref: '#/parameters/limitParam'
         - $ref: '#/parameters/markerParam'
@@ -1028,35 +1029,56 @@ paths:
         - Scheduled Operation
       responses:
         '200':
-          description: An array of operation logs (without the entries)
+          description: An array of operation logs
           schema:
             type: array
             items:
               $ref: '#/definitions/OperationLog'
           examples:
-            application/json: [
+            application/json: {
-              {
+              "operation_logs": [{
-                "id": "23902b02-5666-4ee6-8dfe-962ac09c3994",
+                    "status": "deleted",
-                "scheduled_operation_id": "23902b02-5666-4ee6-8dfe-962ac09c3991",
+                    "provider_id": "cf56bd3e-97a7-4078-b6d5-f36246333fd9",
-                "started_at": "2015-08-27T09:50:58-05:00",
+                    "restore_id": null,
-                "state": "running"
+                    "checkpoint_id": "dbc459ff-2ac6-44fa-ba15-89350d7ebd43",
-              },
+                    "error_info": null,
-              {
+                    "ended_at": "2017-07-28T09:02:57.000000",
-                "id": "23902b02-5666-4ee6-8dfe-962ac09c3994",
+                    "started_at": "2017-07-28T09:02:41.000000",
-                "scheduled_operation_id": "23902b02-5666-4ee6-8dfe-962ac09c3991",
+                    "id": "f0aa664b-f385-4618-bc27-9e0116cceea7",
-                "started_at": "2015-08-27T09:50:58-05:00",
+                    "extra_info": null,
-                "ended_at": "2015-08-27T10:50:58-05:00",
+                    "plan_id": "d58ffd3e-f64e-4b67-9bb0-b86d3483e7d0",
-                "state": "finished"
+                    "scheduled_operation_id": null,
-              },
+                    "operation_type": "protect"
-              {
+                },
-                "id": "23902b02-5666-4ee6-8dfe-962ac09c3994",
+                {
-                "scheduled_operation_id": "23902b02-5666-4ee6-8dfe-962ac09c3991",
+                    "status": "success",
-                "started_at": "2015-08-27T09:50:58-05:00",
+                    "provider_id": "cf56bd3e-97a7-4078-b6d5-f36246333fd9",
-                "ended_at": "2015-08-27T10:50:58-05:00",
+                    "restore_id": "7c0d396a-981b-4953-95f5-30382ddaa8bf",
-                "state": "failed",
+                    "checkpoint_id": "dbc459ff-2ac6-44fa-ba15-89350d7ebd43",
-                "error": "Could not access bank"
+                    "error_info": null,
-              },
+                    "ended_at": "2017-07-28T08:58:08.000000",
-            ]
+                    "started_at": "2017-07-28T08:57:36.000000",
+                    "id": "8736649d-857e-4637-923c-3bdb35edd74e",
+                    "extra_info": null,
+                    "plan_id": null,
+                    "scheduled_operation_id": null,
+                    "operation_type": "restore"
+                },
+                {
+                    "status": "available",
+                    "provider_id": "cf56bd3e-97a7-4078-b6d5-f36246333fd9",
+                    "restore_id": null,
+                    "checkpoint_id": "dbc459ff-2ac6-44fa-ba15-89350d7ebd43",
+                    "error_info": null,
+                    "ended_at": "2017-07-28T08:43:22.000000",
+                    "started_at": "2017-07-28T08:42:02.000000",
+                    "id": "7a16c731-0658-47dd-aa3b-98ee21830e23",
+                    "extra_info": null,
+                    "plan_id": "d58ffd3e-f64e-4b67-9bb0-b86d3483e7d0",
+                    "scheduled_operation_id": null,
+                    "operation_type": "protect"
+                }]
+              }
         default:
           description: Unexpected error
           schema:
@@ -1065,7 +1087,7 @@ paths:
     get:
       summary: Operation log.
       description: |
-        Get the information about a specific run of an operation
+        Get the information about an operation log.
       parameters:
         - $ref: '#/parameters/projectParam'
         - $ref: '#/parameters/operation_log_idParam'
@@ -1074,26 +1096,26 @@ paths:
         - Scheduled Operation
       responses:
         '200':
-          description: An array of operation logs (with the entries)
+          description: The operation log information.
           schema:
               $ref: '#/definitions/OperationLog'
           examples:
             application/json: {
-              "id": "23902b02-5666-4ee6-8dfe-962ac09c3994",
+              "operation_log": {
-              "scheduled_operation_id": "23902b02-5666-4ee6-8dfe-962ac09c3991",
+                  "status": "available",
-              "started_at": "2015-08-27T09:50:58-05:00",
+                  "provider_id": "cf56bd3e-97a7-4078-b6d5-f36246333fd9",
-              "state": "running",
+                  "restore_id": null,
-              "entries": [
+                  "checkpoint_id": "dbc459ff-2ac6-44fa-ba15-89350d7ebd43",
-                {
+                  "error_info": null,
-                  "timestamp": "2015-08-27T09:50:58-05:00",
+                  "ended_at": "2017-07-28T08:43:22.000000",
-                  "message": "Operation started"
+                  "started_at": "2017-07-28T08:42:02.000000",
-                },
+                  "id": "7a16c731-0658-47dd-aa3b-98ee21830e23",
-                {
+                  "extra_info": null,
-                  "timestamp": "2015-08-27T09:50:51-05:00",
+                  "plan_id": "d58ffd3e-f64e-4b67-9bb0-b86d3483e7d0",
-                  "message": "Doing things"
+                  "scheduled_operation_id": null,
-                }
+                  "operation_type": "protect"
-              ]
+              }
-            }
+          }
         default:
           description: Unexpected error
           schema:

doc/source/specs/operation-log-api.rst

@@ -4,9 +4,9 @@
 
  http://creativecommons.org/licenses/by/3.0/legalcode
 
-============================================
+================================================
-Refactor the clients used in protect service
+Add operation log API about protection to Karbor
-============================================
+================================================
 
 https://blueprints.launchpad.net/karbor/+spec/operation-log-api