[openstack-dev] [all][api] POST /api-wg/news
ken1ohmichi at gmail.com
Tue Feb 7 19:04:04 UTC 2017
2017-02-07 6:56 GMT-08:00 Brian Rosmaita <rosmaita.fossdev at gmail.com>:
> On 2/6/17 4:28 PM, Ken'ichi Ohmichi wrote:
>> 2017-02-06 6:45 GMT-08:00 Brian Rosmaita <rosmaita.fossdev at gmail.com>:
>>> On 2/6/17 5:51 AM, Jordan Pittier wrote:
>>> [super-enormous snip -- Chris, Ken, and Jordan make good points, I
>>> encourage you to read the entire thread; I just want to concentrate on
>>> one point]
>>>> I would say we should make compromise, not solve dilemma. I can live in a
>>>> world where we sometimes allow an API change and sometimes prevent it.
>>> I agree with Jordan. We need to look at the context of each specific
>>> case and decide whether a change is OK based on the details. We've
>>> already got the guideline that says "in general", you shouldn't change
>>> the response code, and we respect that. The Glance team isn't claiming
>>> that the guideline is incorrect--we're just saying that given the
>>> context of this specific bug (that is, it's been documented for a long
>>> time to return a 204, all other metadefs DELETE calls are documented to
>>> return a 204, all the other metadefs DELETE calls do in fact return a
>>> 204, etc.), it makes sense that this case is an exception.
>>> Granting an exception here doesn't mean that the floodgates have opened
>>> for an "anything goes" approach to API changes. It just means that an
>>> exception is appropriate in this particular case. I am being a bit
>>> disingenuous there because if an exception is appropriate in this case,
>>> then it will be appropriate in other relevantly similar cases. But
>>> "relevant similarity" will include the entire context of the case, for
>>> example, whether there was a published API contract, whether the other
>>> similar calls behave as documented, etc. From 10,000 meters, it looks
>>> like what we're advocating is "It's OK to change a response code". But
>>> when you look more closely, our claim is that given the details of this
>>> particular bug, it makes sense to fix it in the code and not in the docs.
>>> To summarize, my point is that we shouldn't be worried that this case is
>>> going to set a precedent. It would be worrisome if it were going to set
>>> a *bad* precedent, but when you look at the details of the situation, I
>>> don't think it will. So it looks to me, anyway, that a compromise is in
>>> order here. (In case I'm being too obscure, what I mean is: we should
>>> agree that it's OK for the Glance team to fix this bug in the code with
>>> patch https://review.openstack.org/#/c/420038/.)
>> I feel this case is very common case when we want to chang success status code.
>> Because I cannot find the other motivation for changing success status
>> code except we are finding bugs like this case.
>> So if accepting this case, I guess we drop the following guideline completely
>> The following types of changes are generally *not* considered acceptable:
>> Changing which response code is returned on success.
> I think that's a separate discussion that shouldn't hold up whether we
> can get this particular bug properly fixed soon.
> It doesn't follow that if Glance makes this change, the guideline is
> pointless. As I said earlier, given the context of this particular bug
> (the success code for the call has been documented as a 204, all the
> other metadefs DELETE calls return a 204, all the other calls are also
> documented to return 204s, etc.), one can argue that this is a
> legitimate exception allowed under the guideline. And in fact the API
> Working Group has accepted that argument. If the facts of the case were
> different, they might very well have told me to go boil my head.
> My point here is that we can accept the guideline *and* also accept this
> particular change. Hence, worrying about the status of the guideline is
> not a reason to reject the fix proposed by the patch
> https://review.openstack.org/#/c/420038/ .
Again, this case is not particular case. Very common case.
It was just forgot to specify status code (204 in this case) in the
code, and the wsgi framework returns 200 as the default.
Nova also has multiple same bugs on the API, so I feel this is common case.
My point is "Do we really need to do that ?" with
- Possible to break the existing users APIs
- Break the OpenStack interoperability on multiple different version clouds
- Make the guideline fuzzy when facing the smiler issues
only for us, developers.
More information about the OpenStack-dev