[openstack-dev] [api] Minor changes to API

Matthew Treinish mtreinish at kortar.org
Mon Apr 20 22:23:08 UTC 2015

On Mon, Apr 20, 2015 at 03:10:40PM -0700, Ian Wells wrote:
> On 20 April 2015 at 13:02, Kevin L. Mitchell <kevin.mitchell at rackspace.com>
> wrote:
> > On Mon, 2015-04-20 at 13:57 -0600, Chris Friesen wrote:
> > > > However, minor changes like that could still possibly break clients
> > that are not
> > > > expecting them.  For example, a client that uses the json response as
> > arguments
> > > > to a method via **kwargs would start seeing TypeErrors for unexpected
> > arguments.
> > >
> > > Isn't this what microversions were intended to solve?
> >
> > Yes.
> >
> > > I'm relatively recent with OpenStack, so I don't have the history.  Did
> > anyone
> > > ever consider explicitly allowing new attributes to be added to
> > responses?
> >
> > The problem is advertising that this information is available.
> There are some cases where that's not necessary: a call returns a JSON
> dict.  If, when the dict does not contain the key, some backward compatible
> behaviour is assumed, then you are in fact 100% backward compatible.
> There are other more ambiguous cases, such as setting an attribute that
> doesn't exist in some cases and getting a failure response; there it's nice
> to be able to tell in advance via a detection call what to expect.
> Anyway, I've been bitten by not knowing the unwritten rules so I do agree
> we could use a policy.
> That's
> > why, in the past, nova required a new extension even if all you were
> > doing was adding an attribute, and that's why we want a new microversion
> > nowadays.
> Depends on your  project.  For Neutron:
> - some IPv6 changes introduced new (settable) subnet attributes without a
> bump in version; these were merged in and are now released in Juno
> - the recent VLAN and MTU changes introduced new network attributes without
> a bump in version; these were certainly argued about as a break with
> backward compatibility (and eventually became extensions, though for other
> reasons than simply that one)
> - extensions in Neutron can be used to add attributes without changing the
> core interface; extension detection APIs exist to make planning easier
> It would be nice to have a consistent policy here; it would make future
> decision making easier and it would make it easier to write specs if we
> knew what was expected and the possible implementations weren't up for
> (quite so much) debate.  For different reasons, Neutron extensions are also
> not favoured, so there's no clear cut choice to make.

Uhm, there is: https://wiki.openstack.org/wiki/APIChangeGuidelines
and if you read that adding attrs without advertising it (using an
extension, microversion, or whatever) is not an allowed change. Just adding
things without a new extension or microversion makes the end user story terrible
because it puts the burden completely on the user to try and figure out which 
version 2 (or whatever it currently is marked as) of the api the cloud they're
using speaks. Think about it if it were a library, that just started adding
things to it's interfaces without bumping any version. Even if it was a
backwards compatible addition you would still expect the version to increment to
indicate that the new stuff was there and available for use.

-Matt Treinish
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 819 bytes
Desc: not available
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20150420/19bb53a5/attachment.pgp>

More information about the OpenStack-dev mailing list