api-ref: finish validation for os-server-external-events.inc

This completes the validation for the admin event interface, including
detailing the codes we currently return in the parameter list.

Because os-service was incorrectly using the 'status' key, when I
renamed status => event_status I needed to also create a
service_status to make things compile. It's accurate enough to move
forward.

Because this is really a Neutron only API, this is moved towards the
bottom of the API list, to make it clear this isn't really designed to
be used by end user apps.

Part of bp:api-ref-in-rst

Change-Id: I3ed46eec1c33a63b7a89d6d6b5eeda574effdc56

1 files changed, 29 insertions, 15 deletions

diff --git a/api-ref/source/os-server-external-events.inc b/api-ref/source/os-server-external-events.inc
index 990e1158e7..c652f3299b 100644
--- a/api-ref/source/os-server-external-events.inc
+++ b/api-ref/source/os-server-external-events.inc
@@ -1,12 +1,19 @@
 .. -*- rst -*-
-.. needs:parameter_verification
-.. needs:example_verification
-.. needs:body_verification
 
 ====================================================
  Create external events (os-server-external-events)
 ====================================================
 
+.. warning::
+   This is an ``admin`` level service API only designed to be used by
+   other OpenStack services. The point of this API is to coordinate
+   between Nova and Neutron (and potentially future services) on
+   activities they both need to be involved in, such as network
+   hotplugging.
+
+   Unless you are writing Neutron code you **should not** be using
+   this API.
+
 Creates one or more external events. The API dispatches each event to a
 server instance.
 
@@ -15,14 +22,22 @@ Run Events
 
 .. rest_method:: POST /v2.1/{tenant_id}/os-server-external-events
 
-Creates one or more external events, which the API dispatches to the instance.
+Creates one or more external events, which the API dispatches to the
+host a server is assigned to. If the server is not currently assigned
+to a host the event will not be delivered.
+
+You will receive back the list of events that you submitted, with an
+updated ``code`` and ``status`` indicating their level of success.
 
-You must assign this instance to a host. Otherwise, this call does not dispatch the event to the instance.
+Normal response codes: 200, 207
 
-Normal response codes: 200
+A 200 will be returned if all events succeeded, 207 will be returned
+if some events could not be processed. The ``code`` attribute for the
+event will explain further what went wrong.
 
 Error response codes: badRequest(400), unauthorized(401), forbidden(403),
 itemNotFound(404)
+
 Request
 -------
 
@@ -30,12 +45,12 @@ Request
 
   - tenant_id: tenant_id
   - events: events
-  - name: name
-  - tag: tag
+  - name: event_name
   - server_uuid: server_uuid
-  - status: status
+  - status: event_status
+  - tag: event_tag
 
-**Example Run Events: JSON request**
+**Example Run Events**
 
 .. literalinclude:: ../../doc/api_samples/os-server-external-events/event-create-req.json
    :language: javascript
@@ -47,13 +62,12 @@ Response
 
   - events: events
   - code: code
-  - name: name
+  - name: event_name
   - server_uuid: server_uuid
-  - status: status
-  - tag: tag
+  - status: event_status
+  - tag: event_tag
 
-**Example Run Events: JSON response**
+**Example Run Events**
 
 .. literalinclude:: ../../doc/api_samples/os-server-external-events/event-create-resp.json
    :language: javascript
-