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:

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

Specification

The way in which error codes are returned will be improved by:

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

Quantum-specific status codes defined in the version 1.0 of the API will be mapped to standard HTTP codes as specified in the following table:

|| Standard HTTP status code || Quantum API v1.0 status code ||

400 BadRequest	431 RequestedStateInvalid
404 NotFound	420 NetworkNotFound
404 NotFound	430 PortNotFound
409 Conflict	421 NetworkInUse
	432 PortInUse
	440 AlreadyAttached

Although the current version of the API already provides details about the error in the response body, its structure will be improved in order to simply parsing from clients. In particular:

The 'error code' will be removed as we will not be using anymore status codes; it will be replace by an 'error type' (e.g.: NetworkNotFound, PortInUse);
The root element of the response body will always be 'QuantumError', and not anymore the specific error type;
The 'message' and 'detail' attributes will be left unchanged.

Finally, in order to properly update the client library, it is first necessary to separate the code path used for API v1.0 and API v1.1. Once that is done, it will be possible to parse erroneous response codes for the version 1.1 of the API in a different way.

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 every time 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

As of today, the Quantum client library behaves in the same way regardless of the version of the API used. Also, the Quantum CLI currently supports only version 1.0 of the API.

In order to implemented client-side support for the restructured error code, these issues need to be addressed.

Wiki