Browse Source

Add api definition doc for operation log RESTful API

Change-Id: I2d749adbdca807436ea3dbc1b9c63fa0211a603a
blueprint: operation-log-api
changes/94/491394/4
chenying 4 years ago
parent
commit
70ee9124f3
  1. 1
      api-ref/source/v1/index.rst
  2. 136
      api-ref/source/v1/karbor-v1-operation-logs.inc
  3. 90
      api-ref/source/v1/parameters.yaml
  4. 16
      api-ref/source/v1/samples/operation-log-show-response.json
  5. 48
      api-ref/source/v1/samples/operation-logs-list-response.json
  6. 78
      doc/source/specs/api/api_examples.md
  7. 116
      doc/source/specs/api/karbor_api.v1.yaml
  8. 6
      doc/source/specs/operation-log-api.rst

1
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

136
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

90
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.

16
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"
}
}

48
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"
}]
}

78
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"
}
}
```
----------

116
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.
Whenever an operation is run a log instance is created.
The user never creates operation logs.
This should not include the 'entires' property for the operation log.
Get the operation logs information about different operations(protect, delete, restore)
in karbor protection service.
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: [
{
"id": "23902b02-5666-4ee6-8dfe-962ac09c3994",
"scheduled_operation_id": "23902b02-5666-4ee6-8dfe-962ac09c3991",
"started_at": "2015-08-27T09:50:58-05:00",
"state": "running"
},
{
"id": "23902b02-5666-4ee6-8dfe-962ac09c3994",
"scheduled_operation_id": "23902b02-5666-4ee6-8dfe-962ac09c3991",
"started_at": "2015-08-27T09:50:58-05:00",
"ended_at": "2015-08-27T10:50:58-05:00",
"state": "finished"
},
{
"id": "23902b02-5666-4ee6-8dfe-962ac09c3994",
"scheduled_operation_id": "23902b02-5666-4ee6-8dfe-962ac09c3991",
"started_at": "2015-08-27T09:50:58-05:00",
"ended_at": "2015-08-27T10:50:58-05:00",
"state": "failed",
"error": "Could not access bank"
},
]
application/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"
}]
}
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",
"scheduled_operation_id": "23902b02-5666-4ee6-8dfe-962ac09c3991",
"started_at": "2015-08-27T09:50:58-05:00",
"state": "running",
"entries": [
{
"timestamp": "2015-08-27T09:50:58-05:00",
"message": "Operation started"
},
{
"timestamp": "2015-08-27T09:50:51-05:00",
"message": "Doing things"
}
]
}
"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"
}
}
default:
description: Unexpected error
schema:

6
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

Loading…
Cancel
Save