Open Stack

On 05/06/2015 02:07 PM, Jay Pipes wrote:
> Adding [api] topic. API WG members, please do comment.
> 
> On 05/06/2015 08:01 AM, Sean Dague wrote:
>> On 05/06/2015 07:11 AM, Chris Dent wrote:
>>> On Wed, 6 May 2015, Sean Dague wrote:
>>>
>>>> All other client errors, just be a 400. And use the emerging error
>>>> reporting json to actually tell the client what's going on.
>>>
>>> Please do not do this. Please use the 4xx codes as best as you
>>> possibly can. Yes, they don't always match, but there are several of
>>> them for reasons™ and it is usually possible to find one that sort
>>> of fits.

I agree with Jay here: there are only 100 error codes in the "400"
namespace, and (way) more than 100 possible errors. The general 400 is
perfectly good as a catch-all where the user can be expected to read the
JSON error response for more information, and the other error codes
should be used to make it easier for folks to distinguish specific
conditions.

Let's take the 403 case. If you are denied with your credentials,
there's no error handling that you're going to be able to fix that.

>>> Using just 400 is bad for a healthy HTTP ecosystem. Sure, for the
>>> most part people are talking to OpenStack through "official clients"
>>> but a) what happens when they aren't, b) is that the kind of world
>>> we want?
>>>
>>> I certainly don't. I want a world where the HTTP APIs that OpenStack
>>> and other services present actually use HTTP and allow a diversity
>>> of clients (machine and human).

Wanting other clients to be able to "plug right in" is why we try to be
RESTful and make error codes that are usable by any client (see the
error codes and messages specs). Using "Conflict" and "Forbidden" codes
in addition to good error messages will help, if they denote very
specific conditions that the user can act on.

>> Absolutely. And the problem is there is not enough namespace in the HTTP
>> error codes to accurately reflect the error conditions we hit. So the
>> current model means the following:
>>
>> If you get any error code, it means multiple failure conditions. Throw
>> it away, grep the return string to decide if you can recover.
>>
>> My proposal is to be *extremely* specific for the use of anything
>> besides 400, so there is only 1 situation that causes that to arise. So
>> 403 means a thing, only one thing, ever. Not 2 kinds of things that you
>> need to then figure out what you need to do.

Agreed

>> If you get a 400, well, that's multiple kinds of errors, and you need to
>> then go conditional.
>>
>> This should provide a better experience for all clients, human and
>> machine.
> 
> I agree with Sean on this one.
> 
>>> Using response codes effectively makes it easier to write client code
>>> that is either simple or is able to use generic libraries effectively.
>>>
>>> Let's be honest: OpenStack doesn't have a great record of using HTTP
>>> effectively or correctly. Let's not make it worse.
>>>
>>> In the case of quota, 403 is fairly reasonable because you are in
>>> fact "Forbidden" from doing the thing you want to do. Yes, with the
>>> passage of time you may very well not be forbidden so the semantics
>>> are not strictly matching but it is more immediately expressive yet
>>> not quite as troubling as 409 (which has a more specific meaning).
>>
>> Except it's not, because you are saying to use 403 for 2 issues ("Don't
>> have permissions" and "Out of quota").
>>
>> Turns out, we have APIs for adjusting quotas, which your user might have
>> access to. So part of 403 space is something you might be able to code
>> yourself around, and part isn't. Which means you should always ignore it
>> and write custom logic client side.
>>
>> Using something beyond 400 is *not* more expressive if it has more than
>> one possible meaning. Then it's just muddy. My point is that all errors
>> besides 400 should have *exactly* one cause, so they are specific.
> 
> Yes, agreed.
> 
> I think Sean makes an excellent point that if you have >1 condition that
> results in a 403 Forbidden, it actually does not make things more
> expressive. It actually just means both humans and clients need to now
> delve deeper into the error context to determine if this is something
> they actually don't have permission to do, or whether they've exceeded
> their quota but otherwise have permission to do some action.
> 
> Best,
> -jay
> 
> p.s. And, yes, Chris, I definitely do see your side of the coin on this.
> It's nuanced, and a grey area...
> 
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

-- 
Ryan Brown / Software Engineer, Openstack / Red Hat, Inc.