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

Chris Dent cdent+os at anticdent.org
Fri Feb 3 17:56:07 UTC 2017

On Thu, 2 Feb 2017, Ken'ichi Ohmichi wrote:
> 2017-02-02 9:38 GMT-08:00 Chris Dent <cdent+os at anticdent.org>:
>> Greetings OpenStack community,
>> In today's meeting [0] after briefly covering old business we spent nearly
>> 50 minutes going round in circles discussing the complex interactions of
>> expectations of API stability, the need to fix bugs and the costs and
>> benefits of microversions. We didn't make a lot of progress on the general
>> issues, but we did #agree that a glance issue [4] should be treated as a
>> code bug (not a documentation bug) that should be fixed. In some ways this
>> position is not aligned with the ideal presented by stability guidelines but
>> it is aligned with an original goal of the API-WG: consistency. It's unclear
>> how to resolve this conflict, either in this specific instance or in the
>> guidelines that the API-WG creates. As stated in response to one of the
>> related reviews [5]: "If bugs like this don't get fixed properly in the
>> code, OpenStack risks going down the path of Internet Explorer and people
>> wind up writing client code to the bugs and that way lies madness."
> I am not sure the code change can avoid the madness.

Just for the record, I'm not the speaker of that quote. I included
it because I think it does a good job of representing the complexity
and confusion that we have going on or at least in inspiring
responses that help to do so.

Which is a round about way of saying: Thank you very much for

> If we change the success status code (200 ->204) without any version
> bumps, OpenStack clouds return different status codes on the same API
> operations.
> That will break OpenStack interoperability and clients' APPs need to
> be changed for accepting 204 also as success operation.
> That could make APPs code mudness.
> I also think this is basically code bug, but this is hard to fix
> because of big impact against the existing users.

There have been lots of different opinions and perspective on this
(in the reviews and elsewhere), all of which are pretty sensible but
as a mass are hard to reconcile. The below is reporting evidence, not
supporting a plan:

   The API-WG is striving for OpenStack APIs to be consistent within
   themselves, with each other and with the HTTP RFCs. This particular
   issue is an example where none of those are satisfied.

     Yet it is true that if client code is specifically looking for a
     200 response this change, without a version signal, will break
     that code.

       But glance isn't set up with microversions or something like.

       But isn't checking specifically for 200 as "success" unusual so
       this is unlikely to be as bad as changing a 4xx to some other

       But correcting the docs so they indicate this one request out of
       several in a group breaks the 204 pattern set by the rest of
       the group and could easily be perceived as a typo and thus need
       to be annotated as "special".

How do we reconcile that?

Some opinions of my own:

I worry that we're making it ever harder to fix bugs and technical
debt in many areas of OpenStack. Sure, there are very good reasons
for the constraints we build in, but how much tech debt are we
making ourselves carry? We have the versioning concepts to help (for
those projects that use them) but we haven't yet agreed how to
cleanly deprecate past stuff or even if we can or should.

I don't feel too bad about that worry, because I know there are
plenty of people who worry about other things that balance it out
for a reasonable compromise.

Chris Dent                 ¯\_(ツ)_/¯           https://anticdent.org/
freenode: cdent                                         tw: @anticdent

More information about the OpenStack-dev mailing list