Open Stack

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.
>>
>> 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).
>
> 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.
>
> 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...