Open Stack

On Jan 29, 2015, at 11:41 AM, Sean Dague <sean at dague.net> wrote:

> Correct. This actually came up at the Nova mid cycle in a side
> conversation with Ironic and Neutron folks.
> 
> HTTP error codes are not sufficiently granular to describe what happens
> when a REST service goes wrong, especially if it goes wrong in a way
> that would let the client do something other than blindly try the same
> request, or fail.
> 
> Having a standard json error payload would be really nice.
> 
> {
>     fault: ComputeFeatureUnsupportedOnInstanceType,
>     messsage: "This compute feature is not supported on this kind of
> instance type. If you need this feature please use a different instance
> type. See your cloud provider for options."
> }
> 
> That would let us surface more specific errors.
> 
> Today.... there is a giant hodgepodge - see:
> 
> https://github.com/openstack/tempest-lib/blob/master/tempest_lib/common/rest_client.py#L412-L424
> 
> https://github.com/openstack/tempest-lib/blob/master/tempest_lib/common/rest_client.py#L460-L492
> 
> Especially blocks like this:
> 
>                        if 'cloudServersFault' in resp_body:
>                            message =
> resp_body['cloudServersFault']['message']
>                        elif 'computeFault' in resp_body:
>                            message = resp_body['computeFault']['message']
>                        elif 'error' in resp_body:
>                            message = resp_body['error']['message']
>                        elif 'message' in resp_body:
>                            message = resp_body['message']
> 
> Standardization here from the API WG would be really great.

Agreed. I’m 100% for having a guideline for errors. Good error messages is one of the most important aspects of a good developer experience for an API. I suspect that once you propose an error format for one error, people will immediately think of a lot of valid reasons to have a formant for many errors.

I did a bit of research into prior art for error messages. The best discussion I found on it starts over in JSON-API [1]. It ultimately results in this error format [2]. An example would look like

{
  "errors": [
    {
      "id": "some-transaction-id",
      "href": "https://example.org/more/info/about/this/error.html",
      "code": "0054",
      "title": "foobar must be in the range [foo, bar)"
    },
    {
      "id": "..."
    }
  ]
}

Do we need to use every field in the format? No.
Can we add additional fields as we see fit? Yes.

We need to do what’s best for OpenStack so I’d like to use a format that’s somewhat a standard (at the very least it’s clear that the JSON-API folks have done a lot of thinking on it) but that’s flexible enough to meet our requirements.

I came across some other error formats such as [3] and [4] but found them to be a bit complicated or require things we don’t need.

Thoughts on the JSON-API error format or other formats?

Thanks,
Everett

[1] https://github.com/json-api/json-api/issues/7
[2] http://jsonapi.org/format/#errors
[3] https://github.com/blongden/vnd.error
[4] https://google-styleguide.googlecode.com/svn/trunk/jsoncstyleguide.xml#Reserved_Property_Names_in_the_error_object