Merge "Add services api doc"

api-ref/source/v1/index.rst

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

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

@@ -0,0 +1,115 @@
+.. -*- rst -*-
+
+========
+Services
+========
+Administrator only. Lists all Karbor services, enables or disables a Karbor
+service, freeze or thaw the specified karbor-operationengine host, failover a
+replicating karbor-operationengine host.
+
+
+List All Karbor Services
+========================
+
+.. rest_method:: GET /v1/{tenant_id}/os-services
+
+Lists all Karbor services. Provides details why any services were disabled.
+
+
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - tenant_id: tenant_id
+   - host: host_query
+   - binary: binary_query
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+  - services: services
+  - id: service_id
+  - binary: binary_required
+  - host: host_name_body_req
+  - status: service_status
+  - state: service_state_up_down
+  - updated_at: updated
+  - disabled_reason: disabled_reason_body_req
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/services-list-response.json
+   :language: javascript
+
+
+Update a Karbor Service Status
+==============================
+
+.. rest_method:: PUT /v1/{tenant_id}/os-services/{service_id}
+
+Update a Karbor operationengine service status. Specify the service by its id.
+
+Response codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - tenant_id: tenant_id
+   - service_id: service_id_path
+
+Request Example
+---------------
+
+.. literalinclude:: ./samples/services-update-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - service: service_body
+  - id: service_id
+  - binary: binary_required
+  - host: host_name_body_req
+  - status: service_status
+  - state: service_state_up_down
+  - updated_at: updated
+  - disabled_reason: disabled_reason_body_req
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/services-update-response.json
+   :language: javascript

api-ref/source/v1/parameters.yaml

@@ -50,6 +50,12 @@ restore_id_1:
   in: path
   required: true
   type: UUID
+service_id_path:
+  description: |
+    The ID of the service.
+  in: path
+  required: true
+  type: integer
 tenant_id:
   description: |
     The UUID of the tenant in a multi-tenancy cloud.
@@ -65,6 +71,18 @@ trigger_id_1:
 
 
 # variables in query
+binary_query:
+  description: |
+    Filter the service list result by binary name of the service.
+  in: query
+  required: false
+  type: string
+host_query:
+  description: |
+    Filter the service list result by host name of the service.
+  in: query
+  required: false
+  type: string
 limit:
   description: |
     Requests a page size of items. Returns a number
@@ -95,6 +113,12 @@ sort:
 
 
 # variables in body
+binary_required:
+  description: |
+    The binary name of the service.
+  in: body
+  required: true
+  type: string
 checkpoint:
   description: |
     A ``checkpoint`` object.
@@ -146,6 +170,12 @@ description:
   in: body
   required: true
   type: string
+disabled_reason_body_req:
+  description: |
+    The reason for disabling a service.
+  in: body
+  required: true
+  type: string
 enabled:
   description: |
     "``1``" means ``Enable``, "``0``" means ``Disable``.
@@ -176,6 +206,12 @@ extra_info_1:
   in: body
   required: false
   type: dict
+host_name_body_req:
+  description: |
+    The name of the host.
+  in: body
+  required: true
+  type: string
 links:
   description: |
     Links for transfer.
@@ -492,6 +528,36 @@ schema_saved_info:
   in: body
   required: true
   type: dict
+service_body:
+  description: |
+    A ``service`` object.
+  in: body
+  required: true
+  type: object
+service_id:
+  description: |
+    UUID for the cleanup service.
+  in: body
+  required: true
+  type: integer
+service_state_up_down:
+  description: |
+    The state of the service. One of ``up`` or ``down``.
+  in: body
+  required: true
+  type: string
+service_status:
+  description: |
+    The status of the service. One of ``enabled`` or ``disabled``.
+  in: body
+  required: true
+  type: string
+services:
+  description: |
+    A list of service objects.
+  in: body
+  required: true
+  type: array
 started_at:
   description: |
     The started time of the operation.
@@ -560,3 +626,10 @@ trigger_type:
   in: body
   required: true
   type: string
+updated:
+  description: |
+    The date and time stamp when the extension was
+    last updated.
+  in: body
+  required: true
+  type: string

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

@@ -0,0 +1,27 @@
+{
+  "services": [{
+    "status": "enabled",
+    "binary": "karbor-operationengine",
+    "state": "down",
+    "updated_at": "2019-11-03T11:50:25.000000",
+    "host": "devstack",
+    "disabled_reason": null,
+    "id": 1
+  }, {
+    "status": "enabled",
+    "binary": "karbor-operationengine",
+    "state": "up",
+    "updated_at": "2019-11-11T02:56:05.000000",
+    "host": "devstack",
+    "disabled_reason": null,
+    "id": 2
+  }, {
+    "status": "enabled",
+    "binary": "karbor-protection",
+    "state": "up",
+    "updated_at": "2019-11-11T02:56:03.000000",
+    "host": "devstack",
+    "disabled_reason": null,
+    "id": 3
+  }]
+}

api-ref/source/v1/samples/services-update-request.json

@@ -0,0 +1,4 @@
+{
+  "status": "disabled",
+  "disabled_reason": "service down"
+}

api-ref/source/v1/samples/services-update-response.json

@@ -0,0 +1,11 @@
+{
+  "service": {
+    "status": "disabled",
+    "binary": "karbor-operationengine",
+    "state": "down",
+    "updated_at": "2019-11-03T11:50:25.000000",
+    "host": "devstack",
+    "disabled_reason": null,
+    "id": 1
+  }
+}