api-ref verify of servers-admin-action.inc

verified the API doc for server admin actions,
adjus the wording for default policy,
Also, remove some common error code like 500, 503 etc

The 'backup' action actually is enabled to owner
of the server, follow up patch may move to server
actions.

Part of bp:api-ref-in-rst

Change-Id: I69900f4697bd5b71f0b8f8908037a49eff51b7c6

1 files changed, 77 insertions, 31 deletions

diff --git a/api-ref/source/servers-admin-action.inc b/api-ref/source/servers-admin-action.inc
index 4ec2550b01..8f534694be 100644
--- a/api-ref/source/servers-admin-action.inc
+++ b/api-ref/source/servers-admin-action.inc
@@ -1,7 +1,4 @@
 .. -*- rst -*-
-.. needs:parameter_verification
-.. needs:example_verification
-.. needs:body_verification
 
 ==========================================================
  Servers - run an administrative action (servers, action)
@@ -16,7 +13,7 @@ inject network information into a server.
 You can migrate, live-migrate, reset networking on, and reset the state
 of a server.
 
-Create Server Back Up (Createbackup Action)
+Create Server Back Up (createBackup Action)
 ===========================================
 
 .. rest_method:: POST /v2.1/{tenant_id}/servers/{server_id}/action
@@ -25,11 +22,14 @@ Creates a back up of a server.
 
 Specify the ``createBackup`` action in the request body.
 
-Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the ``policy.json`` file.
+Policy defaults enable only users with the administrative role or the
+owner of the server to perform this operation. Cloud providers can
+change these permissions through the ``policy.json`` file.
 
 Normal response codes: 202
 
-Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)
+Error response codes: badRequest(400), unauthorized(401), forbidden(403),
+itemNotFound(404), conflict(409)
 
 Request
 -------
@@ -39,6 +39,10 @@ Request
   - tenant_id: tenant_id
   - server_id: server_id
   - createBackup: createBackup
+  - name: backup_name
+  - backup_type: backup_type
+  - rotation: backup_rotation
+  - metadata: metadata_image
 
 **Example Create Server Back Up (Createbackup Action): JSON request**
 
@@ -48,7 +52,10 @@ Request
 Response
 --------
 
-Inject Network Information (Injectnetworkinfo Action)
+On success a header 'Location' : <image location URL> and no body
+will be returned.
+
+Inject Network Information (injectNetworkInfo Action)
 =====================================================
 
 .. rest_method:: POST /v2.1/{tenant_id}/servers/{server_id}/action
@@ -57,11 +64,17 @@ Injects network information into a server.
 
 Specify the ``injectNetworkInfo`` action in the request body.
 
-Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the ``policy.json`` file.
+Policy defaults enable only users with the administrative role to
+perform this operation. Cloud providers can change these permissions
+through the ``policy.json`` file.
+
+.. warning:: There is very limited support on this API, For more information,
+             see `nova virt support matrix
+             <http://docs.openstack.org/developer/nova/support-matrix.html>`__
 
 Normal response codes: 202
 
-Error response codes: badRequest(400), unauthorized(401), forbidden(403), conflict(409)
+Error response codes: unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)
 
 Request
 -------
@@ -72,7 +85,7 @@ Request
   - server_id: server_id
   - injectNetworkInfo: injectNetworkInfo
 
-**Example Inject Network Information (Injectnetworkinfo Action): JSON request**
+**Example Inject Network Information (injectNetworkInfo Action): JSON request**
 
 .. literalinclude:: ../../doc/api_samples/os-admin-actions/admin-actions-inject-network-info.json
    :language: javascript
@@ -80,7 +93,9 @@ Request
 Response
 --------
 
-Migrate Server (Migrate Action)
+On success no body is returned.
+
+Migrate Server (migrate Action)
 ===============================
 
 .. rest_method:: POST /v2.1/{tenant_id}/servers/{server_id}/action
@@ -89,11 +104,14 @@ Migrates a server to a host. The scheduler chooses the host.
 
 Specify the ``migrate`` action in the request body.
 
-Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the ``policy.json`` file.
+Policy defaults enable only users with the administrative role to
+perform this operation. Cloud providers can change these permissions
+through the ``policy.json`` file.
 
 Normal response codes: 202
 
-Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)
+Error response codes: badRequest(400), unauthorized(401), forbidden(403)
+itemNotFound(404), conflict(409)
 
 Request
 -------
@@ -104,7 +122,7 @@ Request
   - server_id: server_id
   - migrate: migrate
 
-**Example Migrate Server (Migrate Action): JSON request**
+**Example Migrate Server (migrate Action): JSON request**
 
 .. literalinclude:: ../../doc/api_samples/os-migrate-server/migrate-server.json
    :language: javascript
@@ -112,22 +130,35 @@ Request
 Response
 --------
 
-Live-Migrate Server (Os-Migratelive Action)
+On success no body is returned.
+
+Live-Migrate Server (os-migrateLive Action)
 ===========================================
 
 .. rest_method:: POST /v2.1/{tenant_id}/servers/{server_id}/action
 
 Live-migrates a server to a new host without rebooting.
 
-Use the ``host`` parameter to specify the destination host. If you omit this parameter, the scheduler chooses a host. If a scheduled host is not suitable, the scheduler tries up to ``migrate_max_retries`` rescheduling attempts.
+Specify the ``os-migrateLive`` action in the request body.
+
+Use the ``host`` parameter to specify the destination host. If you
+omit this parameter, the scheduler chooses a host. If a scheduled host
+is not suitable to do migration, the scheduler tries up to
+``migrate_max_retries`` rescheduling attempts.
 
-If both source and destination hosts provide local disks, you can set the ``block_migration`` parameter to ``true``. If either host uses shared storage, the migration fails if you set this parameter to ``true``.
+If both source and destination hosts provide local disks, you can set
+the ``block_migration`` parameter to ``true``. If either host uses
+shared storage, the migration fails if you set this ``block_migration``
+to ``true``.
 
-Policy defaults enable only users with the administrative role to perform this operation. Cloud providers can change these permissions through the ``policy.json`` file.
+Policy defaults enable only users with the administrative role to
+perform this operation. Cloud providers can change these permissions
+through the ``policy.json`` file.
 
 Normal response codes: 202
 
-Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404), conflict(409)
+Error response codes: badRequest(400), unauthorized(401), forbidden(403)
+itemNotFound(404), conflict(409)
 
 Request
 -------
@@ -136,11 +167,11 @@ Request
 
   - tenant_id: tenant_id
   - server_id: server_id
-  - host: host_migration 
+  - host: host_migration
   - block_migration: block_migration
   - disk_over_commit: disk_over_commit
 
-**Example Live-Migrate Server (Os-Migratelive Action): JSON request**
+**Example Live-Migrate Server (os-migrateLive Action): JSON request**
 
 .. literalinclude:: ../../doc/api_samples/os-migrate-server/live-migrate-server.json
    :language: javascript
@@ -148,20 +179,30 @@ Request
 Response
 --------
 
-Reset Networking On A Server (Resetnetwork Action)
+On success no body is returned.
+
+Reset Networking On A Server (resetNetwork Action)
 ==================================================
 
 .. rest_method:: POST /v2.1/{tenant_id}/servers/{server_id}/action
 
-Resets networking on a server.
+Resets networking on a server. 
+
+.. note::
+
+    Only the XenServer driver implements this feature and only if the guest
+    has the XenAPI agent in the targeted server. 
 
 Specify the ``resetNetwork`` action in the request body.
 
-Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the ``policy.json`` file.
+Policy defaults enable only users with the administrative role to
+perform this operation. Cloud providers can change these permissions
+through the ``policy.json`` file.
 
 Normal response codes: 202
 
-Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
+Error response codes: unauthorized(401), forbidden(403), itemNotFound(404),
+conflict(409)
 
 Request
 -------
@@ -172,7 +213,7 @@ Request
   - server_id: server_id
   - resetNetwork: resetNetwork
 
-**Example Reset Networking On A Server (Resetnetwork Action): JSON request**
+**Example Reset Networking On A Server (resetNetwork Action): JSON request**
 
 .. literalinclude:: ../../doc/api_samples/os-admin-actions/admin-actions-reset-network.json
    :language: javascript
@@ -180,7 +221,9 @@ Request
 Response
 --------
 
-Reset Server State (Os-Resetstate Action)
+On success no body is returned.
+
+Reset Server State (os-resetState Action)
 =========================================
 
 .. rest_method:: POST /v2.1/{tenant_id}/servers/{server_id}/action
@@ -189,12 +232,13 @@ Resets the state of a server.
 
 Specify the ``os-resetState`` action and the ``state`` in the request body.
 
-Policy defaults enable only users with the administrative role or the owner of the server to perform this operation. Cloud providers can change these permissions through the ``policy.json`` file.
+Policy defaults enable only users with the administrative role to
+perform this operation. Cloud providers can change these permissions
+through the ``policy.json`` file.
 
 Normal response codes: 202
 
-Error response codes: computeFault(400, 500), serviceUnavailable(503), badRequest(400),
-unauthorized(401), forbidden(403), badMethod(405), itemNotFound(404)
+Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
 
 Request
 -------
@@ -204,8 +248,9 @@ Request
   - tenant_id: tenant_id
   - server_id: server_id
   - os-resetState: os-resetState
+  - os-resetState.state: os-resetState_state
 
-**Example Reset Server State (Os-Resetstate Action): JSON request**
+**Example Reset Server State (os-resetState Action): JSON request**
 
 .. literalinclude:: ../../doc/api_samples/os-admin-actions/admin-actions-reset-server-state.json
    :language: javascript
@@ -213,3 +258,4 @@ Request
 Response
 --------
 
+On success no body is returned.