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

Ken'ichi Ohmichi ken1ohmichi at gmail.com
Fri Feb 3 18:51:24 UTC 2017

2017-02-03 9:56 GMT-08:00 Chris Dent <cdent+os at anticdent.org>:
> On Thu, 2 Feb 2017, Ken'ichi Ohmichi wrote:
>>> 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
> responding.

Haha, I see.

>> 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
>       4xx.
>       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?

This API has been implemented since 2 years ago, and it is easy to
imagine many users are using the API.
If changing success status code like this, we send a message "status
code could be changed anytime" to users and users would recognize "the
success status code is unstable and it is better to check status code
range(20X) instead of a certain code(200, 201, etc) for long-term

If the above is we expect/hope, why should we fix/change success code
to ideal one?
On the above scenario, we are expecting users should not check a certain code.
So even if changing status code, users would not be affected by the change.
Whom we are changing the status code for?
That seems a dilemma.

Ken Ohmichi


> 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
> __________________________________________________________________________
> 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

More information about the OpenStack-dev mailing list