Revision as of 10:59, 12 January 2012

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 only return the following standard HTTP error codes when a request cannot be processed:

• 400 BadRequest: This status code will be returned if the request cannot be accepted by the Quantum server due to its syntax. This status code will replace of 431 RequestedStateInvalid, and will also be returned everytime the Quantum Server is unable to parse the request body.
• 404 NotFound: This status code will be returned if the Quantum server cannot find the requested resource. This status code will be returned in place of 420 NetworkNotFound and 430 PortNotFound, and if the client specifies an invalid request path.
• 409 Conflict: This status code will be returned if the Quantum server is unable to fulfill the request as it is incompatible with its current state, despite being syntactically correct. This status code will replace 421 NetworkInUse, 432 PortInUse, and 440 AlreadyAttached

However clienst might also expect:

• 401 Unauthorized/403 Forbidden. These status codes might be returned if authentication/authorization modules are inserted in the Quantum pipeline. The Keystone integration module for Quantum only returns 401 errors.
• 500 InternalServerError. This status code will be returned if an unexpected error is caught in the Quantum server.

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, clients might find difficult to parse error messages structured in this way, especially if the code of the error is no more in the HTTP response status. For this reason, the response body of an error message, will be restructured in the following way:

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

In this way each error message will always be parsed in the same way. Please note that the error code attribute has been removed as it seems there's no need anymore to keep Quantum-specific error codes (the 'type' attribute should be sufficient to this aim).

Client-Side changes