7.6 KiB
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.
History
Release Name | Description |
---|---|
Queens | Introduced |
Rocky | Re-proposed |