[openstack-dev] [Ironic] Let's talk about API versions

Jim Rollenhagen jim at jimrollenhagen.com
Tue Jul 28 20:56:26 UTC 2015


On Tue, Jul 28, 2015 at 08:23:34PM +0000, Devananda van der Veen wrote:
> On Mon, Jul 27, 2015 at 4:58 PM Sean Dague <sean at dague.net> wrote:
> 
> > On 07/27/2015 07:10 PM, Jim Rollenhagen wrote:
> > > On Mon, Jul 27, 2015 at 03:28:49PM -0700, Clint Byrum wrote:
> > >> Excerpts from Sean Dague's message of 2015-07-27 13:41:20 -0700:
> > >>> So the CLI should actually break less often, and will expose the most
> > >>> functionality you can get out of your cloud.
> > >>>
> > >>
> > >> What I find odd about this is that I want the CLI to be a faithful
> > >> representation of the API, because many times the CLI is the only way I
> > >> can access the API for integration purposes.
> > >
> > > "Faithful representation of the API" is an interesting way to put it; it
> > > is a "faithful representation" either way. This way is a representation
> > > of the newest state of the API. It sounds like you're expecting a
> > > representation of the oldest state, or the state that you're used to
> > > (the hardest to predict).
> > >
> > >>
> > >> So lets say I just want a very simple bash script to do something with
> > >> nodes:
> > >>
> > >> id=$(ironic node-create ...|getid)
> > >> while true ; do
> > >>   state=$(ironic node-get $id | get_state)
> > >>   case $state in
> > >>   AVAILABLE)
> > >>     break;;
> > >>   ERROR)
> > >>     # retry or something
> > >>     ;;
> > >>   *)
> > >>     splode("UNKNOWN STATE")
> > >>     ;;
> > >>   esac
> > >> done
> > >>
> > >> Then the script is going to start exploding with a CLI that shows me
> > >> ENROLL state.
> > >>
> > >> So I'm not sure having the CLI go faster than the python client is a
> > >> great way to avoid breakage. It might be the opposite of that, and that
> > >> might just be a large burden on users.
> > >
> > > I tend to think that folks using the CLI for automation should be
> > > pinning the version in that automation. A quick IRONIC_API_VERSION=1.8
> > > or whatever would solve this problem. When new versions are available,
> > > read the notes for that version and adjust your code as necessary. Or
> > > just leave it at the same version until it breaks. :)
> >
> > Yeh, it's a cli, not a bash API. Having had to maintain devstack
> > exercise code for a while, I'll tell you that the above is just a time
> > bomb waiting to go off. None of the CLIs have that kind of contract, nor
> > should they. Inflicting the bad UX of today on future generations
> > because someone thinks, incorrectly, that it's a bash SDK is not a good
> > trade off.
> >
> >
> And people script against that CLI all. the. time.
> 
> Is it pretty? No. But is it something that people do? Yep.
> 
> Does that mean we should try to care? Yea, I think so, and I think that
> means we should try to avoid breaking it when reasonably possible.
> 
> 
> > If you want to pin things, explicitly, like jroll said, do that. And
> > microversions lets you until your clouds uplift past your legacy code.
> >
> 
> "if you want to pin the version" != "all users must explicitly specify the
> version"
> 
> I believe Jim is advocating for the latter. I'm advocating for the former.

The problem that I'm now seeing is you're advocating not just that
people should be able to pin a version. You're advocating for:

1. People don't need to pin the version. Fine.
   1.1. Side note: perhaps you're actually advocating for "people should
        not need to pin the version"? It's starting to sound that way.
2. The client should always default to the most recent compatible
  version. Fine.
3. We should never break a user. Fine.
4. 1-3 must all be true always. Not fine.

We can't reasonably make progress while having the latest API version be
compatible with the previous API version. The combination above breaks
down when we also want to continue to produce software (preferably
quickly). We need to let one of those things go; they can't all be true
at the same time.

I think the best thing to let go is 1 or 2, personally. Where we are
today is letting 3 go, and that's why we're stuck here.

// jim

> 
> 
> -Deva

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