nova/api-ref/source/os-server-external-events.inc
Eric Fried e6f7425444 Nix os-server-external-events 404 condition
The POST /os-server-external-events API had the following confusing
behavior:

With multiple events in the payload, if *some* (but not all) were
dropped, the HTTP response was 207, with per-event 4xx error codes in
the payload. But if *all* of the events were dropped, the overall HTTP
response was 404 with no payload. Thus, especially for consumers sending
only one event at a time, it was impossible to distinguish e.g. "you
tried to send an event for a nonexistent instance" from "the instance
you specified hasn't landed on a host yet".

This fix gets rid of that sweeping 404 condition, so if *any* subset of
the events are dropped (including *all* of them), the HTTP response will
always be 207, and the payload will always contain granular per-event
error codes.

This effectively means the API can no longer return 404, ever.

Closes-Bug: #1855752
Change-Id: Ibad1b51e2cf50d00102295039b6e82bc00bec058
2019-12-09 11:52:49 -06:00

78 lines
2.2 KiB
ReStructuredText

.. -*- rst -*-
====================================================
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, Nova and Cinder, Nova and Ironic (and potentially
future services) on activities they both need to be involved in,
such as network hotplugging.
Unless you are writing Neutron, Cinder or Ironic code you **should not**
be using this API.
Creates one or more external events. The API dispatches each event to a
server instance.
Run Events
==========
.. rest_method:: POST /os-server-external-events
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.
Normal response codes: 200, 207
A 200 will be returned if all events succeeded, 207 will be returned
if any 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)
.. note:: Prior to the fix for `bug 1855752`_, error response code 404 may be
erroneously returned when all events failed.
.. _bug 1855752: https://bugs.launchpad.net/nova/+bug/1855752
Request
-------
.. rest_parameters:: parameters.yaml
- events: events
- name: event_name
- server_uuid: server_uuid
- status: event_status
- tag: event_tag
**Example Run Events**
.. literalinclude:: ../../doc/api_samples/os-server-external-events/event-create-req.json
:language: javascript
Response
--------
.. rest_parameters:: parameters.yaml
- events: events
- code: code
- name: event_name
- server_uuid: server_uuid
- status: event_status
- tag: event_tag
**Example Run Events**
.. literalinclude:: ../../doc/api_samples/os-server-external-events/event-create-resp.json
:language: javascript