[openstack-dev] [all][api] POST /api-wg/news
jordan.pittier at gmail.com
Mon Feb 6 10:51:56 UTC 2017
On Fri, Feb 3, 2017 at 7:51 PM, Ken'ichi Ohmichi <ken1ohmichi at gmail.com>
> 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  after briefly covering old business we spent
> >>> nearly
> >>> 50 minutes going round in circles discussing the complex interactions
> >>> 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  should be treated as
> >>> code bug (not a documentation bug) that should be fixed. In some ways
> >>> this
> >>> position is not aligned with the ideal presented by stability
> >>> 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
> >>> guidelines that the API-WG creates. As stated in response to one of the
> >>> related reviews : "If bugs like this don't get fixed properly in the
> >>> code, OpenStack risks going down the path of Internet Explorer and
> >>> 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
I think we should be pragmatic. There's a a difference between changing one
return code from 200->204 (still in the 2XX range), for one endpoint
exceptionally and saying "we keep changing status code, OpenStack is not
Microversions are great, but not all projects support them yet. In the mean
time, if a project properly documents through a release note a minor API
change (like this one), that sounds reasonable. Sure some user code will
break, at upgrade, but let's be realistic here things get broken after a
major upgrade of every software, that's why operators/deployers test the
> 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
> So even if changing status code, users would not be affected by the change.
> Whom we are changing the status code for?
That's a good question. In that case we should do it "for us, the
developers". I prefer to work with a sane code base, sane API, small
technical debt. But I also understand the users are paying us for
> That seems a dilemma.
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.
> 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:
> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the OpenStack-dev