Quantum-api-error-codes

Reviewing Quantum API error codes

Summary

This blueprint aims at reviewing the way in which Quantum returns error codes to clients for the upcoming Essex release. The current release of the Quantum API (1.0) uses HTTP response codes for communicating application-level errors (for instance 420 NetworkNotFound).

The need for this change in the Quantum API arises from the following considerations:

1. Quantum clients might use libraries for RESTFul APIs which expect only standard HTTP response codes;
2. There's no guarantee in the future some error codes used by Quantum will be employed by the IETF for HTTP response codes
3. The other Openstack projects only use standard HTTP error codes.

Specification

This blueprints aim at improving the way in which error codes are returned, by:

1. Using only standard HTTP response codes, such as 400 Bad Request or 401 Unauthorized
2. Embedding Quantum-specific details into the response body
3. Updating the client library in order to reflect these changes

Implementation

Server-Side changes

The Quantum API will always return a 400 BadRequest error

The response body associated with a Quantum error already contains an attribute with the error code:

<networkNotFound xmlns="http://netstack.org/quantum/api/v1.0">
   <code>
       420
   </code>
   <message>
       Unable to find a network with the specified identifier.
   </message>
   <detail>
       Network 8de6af7c-ef95-4ac1-9d37-172f8df33a1f could not be found
   </detail>
</networkNotFound>

However, error messages structured in this way are not easy to parse as ...