nova-specs/specs/rocky/implemented/placement-api-error-handling.rst

..
 This work is licensed under a Creative Commons Attribution 3.0 Unported
 License.

 http://creativecommons.org/licenses/by/3.0/legalcode

============================
Placement API error handling
============================

https://blueprints.launchpad.net/nova/+spec/placement-api-error-handling

This blueprint aims to extend the placement API to include detailed, consistent
error messages in the response body to allow clear distinctions between
different errors that use the same HTTP status code.

Problem description
===================

Error conditions in the placement REST API are signalled by HTTP status codes
and message bodies. For some of the errors it is impossible to distinguish the
reason why a particular response was issued other than reading the message
which was returned in the response body. This approach creates a strong
coupling between client code and the exact message of the error response. This
is very fragile in the face of change.

Use Cases
---------

As a consumer of the placement API, I want to be able to clearly distinguish
the different reasons for failed requests, especially in the case where there
are different causes for the same HTTP status code, so that I can react to each
case accordingly.

Proposed change
===============

We propose to extend existing HTTP error responses with a ``code`` field as
described in the API-WG Errors_ specification. This will help consumers of the
API to easily recognize the type of the error cases. Note that the new format
of the response is for ``application/json`` only (because of the way WebOb is
used it is possible, if the ``accept`` header specifies something other than
``application/json``, to get an error response that is ``text/plain`` or
``text/html``).

The exact implementation for doing this requires some experimentation. Webob's
error formatting makes it quite challenging to get at the desired information
(the formatter does not have clean access to the exception object). The most
straightforward thing to do is to inject the WSGI ``environ`` with the required
information when creating an exception. Doing this elegantly is where the
experimentation comes in. There is a `work in progress`_ spike.

This spec does not propose changing every error response. Instead the goal is
to add the framework that makes it possible for the ``code`` field to be
defined as required. This is for at least two reasons:

* Making all the changes at once will require a lot of churn in the code for
  limited immediate value.
* Delaying implementation while we determine a complete ontology for placement
  error responses may delay us until the heat death of the universe.

For those errors where a specific code is not yet required, a generic code will
be present. A new microversion will be created. Before that microversion, no
code is present. After that microversion a code will always be present but it
will not always be specific to any given error.

Alternatives
------------

We can keep things as they are, examining strings in the returned messages from
the API response to determine what the cause was for a certain error. This is
considered insufficiently robust.

We can more completely implement the Errors_ specification by also adding a
``help`` link that points to documentation that explains the error code. That
is not proposed here as it depends on building a new collection of
documentation, and the immediate need is to be able effectively distinguish
errors. If it turns out that we want it, we can always add it later.

We could consider whether we need or want the addition of codes to individual
error responses to be bounded by a microversion. Historically, changes in error
bodies have not required a microversion, but in this case the presence of the
code enables a different code path in the client (check the code instead of
parse a string). Signalling this by way of a microversion could be nice but at
the same time code could just check for the `code` key in the response.
Another option could be to microversion as needed. For example, the case of
inventory violation conflicts (versus generation conflicts), might be a good
choice. The model of handling microversions described in the proposed change
above is preferred as it is simpler.

Data model impact
-----------------

None

REST API impact
---------------

A framework will be added such that when raising WebOb-based exceptions,
a code can optionally be added which, if present, will extend the JSON-based
error response.

This means that responses that looked like this::

  Content-Type: application/json
  {
    "errors": [
      {
        "status": [status],
        "title": "[title]",
        "detail": "[detail]",
        "request_id": "[request_id]"
        ]
      }
    ]
  }

will gain a ``code`` field as follows::

  Content-Type: application/json
  {
    "errors": [
      {
        "code": "[code]",
        "status": [status],
        "title": "[title]",
        "detail": "[detail]",
        "request_id": "[request_id]"
        ]
      }
    ]
  }

``code`` is a unique and meaningful string for each error condition with a
prefix of ``placement.``. For instance, when creating a new resource provider,
if the name of the resource provider already exists and a ``409`` response is
made, it is distinguished from other ``409`` responses by a code of
``placement.resource_provider.name_exists``.

.. note:: It is not the purpose of this specification to come up with a naming
          scheme for error codes. The above is an example only.

The ``code`` string is unique to the handler methods in the placement API code
that raises the exception. Once a code is chosen for a specific error situation
it must not change.

Exceptions that are raised without a code will receive a generic code. The
expectation is that more specific codes will be added incrementally, as
required.

The initial addition of ``code`` support will be done in a microversion change,
but later additions of new codes will not.

Security impact
---------------

None

Notifications impact
--------------------

None

Other end user impact
---------------------

None

Performance Impact
------------------

None

Other deployer impact
---------------------

None

Developer impact
----------------

As codes are added to error responses, client code will be able to use them to
distinguish between errors that have the same HTTP status code.

Upgrade impact
--------------

None.


Implementation
==============

Assignee(s)
-----------

Primary assignee:
  Chris Dent (cdent)

Work Items
----------

* Determine best method for providing the information to
  ``json_error_formatter``.
* Update at least one handler to provide ``code`` for an exception it
  explicitly raises.
* Update gabbi tests accordingly.
* Document the added codes in the `placement api-ref`_.
* Document the need to add codes in the `placement contributor docs`_.

Dependencies
============

None

Testing
=======

Update/provide new gabbi tests that check for error codes.

Documentation Impact
====================

The `placement api-ref`_ will be updated to reflect the addition of codes on
those error responses that are changed.

References
==========

* Errors_ description from API-WG.
* A spiked `work in progress`_.


.. _Errors:  http://specs.openstack.org/openstack/api-wg/guidelines/errors.html
.. _work in progress: https://review.openstack.org/#/c/546177/
.. _placement api-ref: https://developer.openstack.org/api-ref/placement/
.. _placement contributor docs: https://docs.openstack.org/nova/latest/contributor/placement.html

History
=======

.. list-table:: Revisions
   :header-rows: 1

   * - Release Name
     - Description
   * - Queens
     - Introduced
   * - Rocky
     - Re-proposed