[openstack-dev] [all][api] POST /api-wg/news

Ken'ichi Ohmichi ken1ohmichi at gmail.com
Mon Feb 6 21:28:13 UTC 2017

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.
> +1000
> 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[1]

  The following types of changes are generally *not* considered acceptable:
       Changing which response code is returned on success.

Ken Ohmichi

[1]: https://specs.openstack.org/openstack/api-wg/guidelines/evaluating_api_changes.html#guidance

More information about the OpenStack-dev mailing list