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

History

Revisions

Release Name

Description

Queens

Introduced

Rocky

Re-proposed