api-ref, os-services.inc

Verified parameters, examples, body text.
Included v2.11 sample files for GET and PUT
os-services.

Part of: bp/api-ref-in-rst

Change-Id: Ice4fb525d62230b2e20f01789a0aec396835b56b

api-ref/source/os-services.inc

@@ -1,7 +1,4 @@
 .. -*- rst -*-
-.. needs:parameter_verification
-.. needs:example_verification
-.. needs:body_verification
 
 ================================
  Compute services (os-services)
@@ -21,7 +18,7 @@ List Compute Services
 
 Lists all running Compute services.
 
-Includes reasons, if available, for why any services were disabled.
+Provides details why any services were disabled.
 
 Normal response codes: 200
 
@@ -33,61 +30,19 @@ Response
 .. rest_parameters:: parameters.yaml
 
   - services: services
-  - id: id
+  - id: service_id_body
   - binary: binary
-  - disabled_reason: disabled_reason
+  - disabled_reason: disabled_reason_body
-  - host: host
+  - host: host_name_body
   - state: service_state
   - status: service_status
   - updated_at: updated
   - forced_down: forced_down
   - zone: OS-EXT-AZ:availability_zone
 
-**Example List Compute Services: JSON response**
+**Example List Compute Services**
 
-.. literalinclude:: ../../doc/api_samples/os-services/services-list-get-resp.json
+.. literalinclude:: ../../doc/api_samples/os-services/v2.11/services-list-get-resp.json
-   :language: javascript
-
-Enable Scheduling For A Compute Service
-=======================================
-
-.. rest_method:: PUT /os-services/enable
-
-Enables scheduling for a Compute service.
-
-Specify the service by its host name and binary name.
-
-Normal response codes: 200
-
-Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)
-
-Request
--------
-
-.. rest_parameters:: parameters.yaml
-
-
-  - host: host
-  - binary: binary
-
-**Example Enable Scheduling For A Compute Service: JSON request**
-
-.. literalinclude:: ../../doc/api_samples/os-services/service-enable-put-req.json
-   :language: javascript
-
-Response
---------
-
-.. rest_parameters:: parameters.yaml
-
-  - service: service
-  - binary: binary
-  - host: host
-  - status: service_status
-
-**Example Enable Scheduling For A Compute Service: JSON response**
-
-.. literalinclude:: ../../doc/api_samples/os-services/service-enable-put-resp.json
    :language: javascript
 
 Disable Scheduling For A Compute Service
@@ -95,7 +50,7 @@ Disable Scheduling For A Compute Service
 
 .. rest_method:: PUT /os-services/disable
 
-Disables scheduling for a Compute service.
+Disables scheduling for a Compute service with optional logging.
 
 Specify the service by its host name and binary name.
 
@@ -108,11 +63,10 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-
+  - host: host_name_body
-  - host: host
   - binary: binary
 
-**Example Disable Scheduling For A Compute Service: JSON request**
+**Example Disable Scheduling For A Compute Service**
 
 .. literalinclude:: ../../doc/api_samples/os-services/service-disable-put-req.json
    :language: javascript
@@ -124,10 +78,10 @@ Response
 
   - service: service
   - binary: binary
-  - host: host
+  - host: host_name_body
   - status: service_status
 
-**Example Disable Scheduling For A Compute Service: JSON response**
+**Example Disable Scheduling For A Compute Service**
 
 .. literalinclude:: ../../doc/api_samples/os-services/service-disable-put-resp.json
    :language: javascript
@@ -150,12 +104,11 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-
+  - host: host_name_body
-  - host: host
   - binary: binary
-  - disabled_reason: disabled_reason
+  - disabled_reason: disabled_reason_body
 
-**Example Log Disabled Compute Service Information: JSON request**
+**Example Log Disabled Compute Service Information**
 
 .. literalinclude:: ../../doc/api_samples/os-services/service-disable-log-put-req.json
    :language: javascript
@@ -167,15 +120,102 @@ Response
 
   - service: service
   - binary: binary
-  - disabled_reason: disabled_reason
+  - disabled_reason: disabled_reason_body
-  - host: host
+  - host: host_name_body
   - status: service_status
 
-**Example Log Disabled Compute Service Information: JSON response**
+**Example Log Disabled Compute Service Information**
 
 .. literalinclude:: ../../doc/api_samples/os-services/service-disable-log-put-resp.json
    :language: javascript
 
+Enable Scheduling For A Compute Service
+=======================================
+
+.. rest_method:: PUT /os-services/enable
+
+Enables scheduling for a Compute service.
+
+Specify the service by its host name and binary name.
+
+Normal response codes: 200
+
+Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - host: host_name_body
+  - binary: binary
+
+**Example Enable Scheduling For A Compute Service**
+
+.. literalinclude:: ../../doc/api_samples/os-services/service-enable-put-req.json
+   :language: javascript
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+  - service: service
+  - binary: binary
+  - host: host_name_body
+  - status: service_status
+
+**Example Enable Scheduling For A Compute Service**
+
+.. literalinclude:: ../../doc/api_samples/os-services/service-enable-put-resp.json
+   :language: javascript
+
+Update Forced Down
+==================
+
+.. rest_method:: PUT /os-services/force-down
+
+Set or unset ``forced_down`` flag for the service.
+
+Action ``force-down`` available as of microversion 2.11.
+
+Specify the service by its host name and binary name.
+
+Normal response codes: 200
+
+Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404)
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - host: host_name_body
+  - binary: binary
+  - forced_down: forced_down
+
+**Example Update Forced Down**
+
+.. literalinclude:: ../../doc/api_samples/os-services/v2.11/service-force-down-put-req.json
+   :language: javascript
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+  - service: service
+  - binary: binary
+  - forced_down: forced_down
+  - host: host_name_body
+
+|
+
+**Example Update Forced Down**
+
+.. literalinclude:: ../../doc/api_samples/os-services/v2.11/service-force-down-put-resp.json
+   :language: javascript
+
 Delete Compute Service
 ======================
 
@@ -197,3 +237,5 @@ Request
 
 Response
 --------
+
+No response returned in body upon successful DELETE.

api-ref/source/parameters.yaml

@@ -86,7 +86,7 @@ console_id:
   type: string
 disabled_reason:
   description: |
-    The reason for disable a service.
+    The reason for disabling a service.
   in: path
   required: false
   type: string
@@ -241,11 +241,11 @@ server_id_path:
   required: true
   type: string
 service_id_path:
+  description: |
+    The id of the service.
   in: path
   required: true
-  type: int
+  type: integer
-  description: |
-    The id of the service
 snapshot_id_2:
   description: |
     The UUID of the snapshot.
@@ -1188,6 +1188,12 @@ device_resp:
   in: body
   required: true
   type: string
+disabled_reason_body:
+  description: |
+    The reason for disabling a service.
+  in: body
+  required: true
+  type: string
 disk_available_least:
   description: |
     The actual free disk on this hypervisor(in GB).
@@ -1537,13 +1543,14 @@ force_live_migrate:
   type: boolean
   min_version: 2.30
 forced_down:
-  in: body
-  required: true
-  type: boolean
   description: |
     Whether or not this service was forced down manually by an
     administrator. This value is useful to know that some 3rd party has
     verified the service should be marked down.
+  in: body
+  required: true
+  type: boolean
+  min_version: 2.11
 forceDelete:
   description: |
     The action.
@@ -3201,47 +3208,47 @@ server_uuid:
   type: string
 servers:
   description: |
-    List of ``server`` objects.
+    A list of ``server`` objects.
   in: body
   required: true
   type: array
 service:
+  description: |
+    Object representing a compute service.
   in: body
   required: true
   type: object
-  description: |
-    Object representing a compute service
 service_disable_reason:
-  in: body
-  required: true
-  type: string
   description: |
     The disable reason of the service, ``null`` if the service is enabled or
     disabled without reason provided.
+  in: body
+  required: true
+  type: string
 service_id_body:
+  description: |
+    The id of the service.
   in: body
   required: true
   type: integer
-  description: |
-    The id of the service
 service_state:
-  in: body
-  required: true
-  type: string
   description: |
     The state of the service. One of ``up`` or ``down``.
-service_status:
   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
-  description: |
-    An array of service objects
 set_metadata:
   description: |
     The set_metadata object used to set metadata for host aggregate.