Open Stack

Hi All,

An API Working Group Guideline for Errors

https://review.openstack.org/#/c/167793/

Errors are a crucial part of the developer experience when using an API. As developers learn the API they inevitably run into errors. The quality and consistency of the error messages returned to them will play a large part in how quickly they can learn the API, how they can be more effective with the API, and how much they enjoy using the API.

We need consistency across all services for the error format returned in the response body.


The Way Forward

I did a bit of research into the current state of consistency in errors across OpenStack services [1]. Since no services seem to respond with a top-level "errors" key, it's possible that they could just include this key in the response body along with their usual response and the 2 can live side-by-side for some deprecation period. Hopefully those services with unstructured errors should okay with adding some structure. That said, the current error formats aren't documented anywhere that I've seen so this all feels fair game anyway.

How this would get implemented in code is up to you. It could eventually be implemented in all projects individually or perhaps a Oslo utility is called for. However, this discussion is not about the implementation. This discussion is about the error format.


The Review

I’ve explicitly added all of the API WG and Logging WG CPLs as reviewers to that patch but feedback from all is welcome. You can find a more readable version of patch set 4 at [2]. I see the "id" and “code” fields as the connection point to what the logging working group is doing.


Thanks,
Everett


[1] https://wiki.openstack.org/wiki/API_Working_Group/Current_Design/Errors
[2] http://docs-draft.openstack.org/93/167793/4/check/gate-api-wg-docs/e2f5b6e//doc/build/html/guidelines/errors.html