From 16b29024c255ecdf34e8fa1a88613646c8810bce Mon Sep 17 00:00:00 2001 From: Chris Dent Date: Wed, 12 Dec 2018 14:19:45 +0000 Subject: [PATCH] Document API error codes Add a section to the api-ref describing the error codes that some responses produce. Note in the contributor docs that this should be updated when one is added. The reshaper docs is adjusted so a ref can be made to it from the errors. The implicit link to the header that would be the norm there doesn't work as there are two headers named "Reshaper". Change-Id: I89bbd383ba102fdd707ccc9f2fc973c6dd841fa8 Closes-Bug: #1794712 --- api-ref/source/errors.inc | 69 ++++++++++++++++++++++++++++++++ api-ref/source/index.rst | 1 + api-ref/source/reshaper.inc | 3 ++ doc/source/contributor/index.rst | 5 ++- 4 files changed, 77 insertions(+), 1 deletion(-) create mode 100644 api-ref/source/errors.inc diff --git a/api-ref/source/errors.inc b/api-ref/source/errors.inc new file mode 100644 index 000000000..4419162c0 --- /dev/null +++ b/api-ref/source/errors.inc @@ -0,0 +1,69 @@ +====== +Errors +====== + +When there is an error interacting with the placement API, the response will +include a few different signals of what went wrong, include the status header +and information in the response body. The structure of the ``JSON`` body of an +error response is defined by the OpenStack errors_ guideline. + +**HTTP Status Code** + The ``Status`` header of the response will include a code, defined by + :rfc:`7231#section-6` that gives a general overview of the problem. + This value also shows up in a ``status`` attribute in the body of the + response. + +**Detail Message** + A textual description of the error condition, in a ``detail`` attribute. + The value is usually the message associated with whatever exception + happened within the service. + +**Error Code** + When the microversion is ``>=1.23`` responses will also include a ``code`` + attribute in the ``JSON`` body. These are documented below. Where a + response does not use a specific code ``placement.undefined_code`` is + present. + +.. note:: In some cases, for example when keystone is being used and no + authentication information is provided in a request (causing a + ``401`` response), the structure of the error response will not match + the above because the error is produced by code other than the + placement service. + + +Error Codes +=========== + +The defined errors are: + +.. list-table:: + :header-rows: 1 + + * - Code + - Meaning + * - ``placement.undefined_code`` + - The default code used when a specific code has not been defined or is + not required. + * - ``placement.inventory.inuse`` + - An attempt has been made to remove or shrink inventory that has capacity + in use. + * - ``placement.concurrent_update`` + - Another operation has concurrently made a request that involves one or + more of the same resources referenced in this request, changing state. + The current state should be retrieved to determine if the desired + operation should be retried. + * - ``placement.duplicate_name`` + - A resource of this type already exists with the same name, and duplicate + names are not allowed. + * - ``placement.resource_provider.inuse`` + - An attempt was made to remove a resource provider, but there are + allocations against its inventory. + * - ``placement.resource_provider.cannot_delete_parent`` + - An attempt was made to remove a resource provider, but it has one or + more child providers. They must be removed first in order to remove this + provider. + * - ``placement.resource_provider.not_found`` + - A resource provider mentioned in an operation involving multiple + resource providers, such as :ref:`reshaper`, does not exist. + +.. _errors: https://specs.openstack.org/openstack/api-wg/guidelines/errors.html diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst index 30c900195..c356454ed 100644 --- a/api-ref/source/index.rst +++ b/api-ref/source/index.rst @@ -15,6 +15,7 @@ header for APIs sending data payloads in the request body (i.e. ``PUT`` and .. rest_expand_all:: .. include:: request-ids.inc +.. include:: errors.inc .. include:: root.inc .. include:: resource_providers.inc .. include:: resource_provider.inc diff --git a/api-ref/source/reshaper.inc b/api-ref/source/reshaper.inc index ee68bce03..4d23a8913 100644 --- a/api-ref/source/reshaper.inc +++ b/api-ref/source/reshaper.inc @@ -1,3 +1,6 @@ + +.. _reshaper: + ======== Reshaper ======== diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 0979291db..817d93168 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -157,6 +157,8 @@ the code: ``placement/tests/functional/gabbits/microversion.yaml``. * Update the `API Reference`_ documentation as appropriate. The source is located under ``api-ref/source/``. +* If a new error code has been added in ``placement/errors.py``, it should + be added to the `API Reference`_. In the placement API, microversions only use the modern form of the version header:: @@ -265,7 +267,8 @@ by using the ``comment`` kwarg to a WebOb exception, like this:: comment=errors.INVENTORY_INUSE) Code that adds newly raised exceptions should include an error code. Find -additional guidelines on use in the docs for ``placement.errors``. +additional guidelines on use in the docs for ``placement.errors``. When a +new error code is added, also document it in the `API Reference`_. Testing of handler code is described in the next section.