Re: [openstack-dev] [api] Minor changes to API
On 20 April 2015 at 17:52, David Kranz dkr...@redhat.com wrote: On 04/20/2015 08:07 PM, Ian Wells wrote: Whatever your preference might be, I think it's best we lose the ambiguity. And perhaps advertise that page a little more widely, actually - I hadn't come across it in my travels. And perhaps improve its air of authority: rules on this subject should probably live somewhere in a repo so that it's clear there's consensus for changes. Currently anyone can change it for any reason, and two years after the last substantive change it's hard to say who even knew it was being changed, let alone whether they agreed. This page has some kind of authority as it is linked to from https://wiki.openstack.org/wiki/Governance/Approved/APIStability. At that time the guidelines were a work in progress but clearly at this point it belongs in a more controlled repo. That said, this document has been referenced many times on the dev list and I am not sure that just moving it to a repo would increase awareness. It would also need to be more advertised. Yeah - the repo was more an issue of authority, so that when it changes it's clear that it's been changed and people checked the change. The awareness thing is probably something that PTLs need to propagate - reviewers need to know of it and what it says and check it when approving API-affecting changes. -- Ian. __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Minor changes to API
On Apr 20, 2015, at 7:07 PM, Ian Wells ijw.ubu...@cack.org.ukmailto:ijw.ubu...@cack.org.uk wrote: On 20 April 2015 at 15:23, Matthew Treinish mtrein...@kortar.orgmailto:mtrein...@kortar.org wrote: On Mon, Apr 20, 2015 at 03:10:40PM -0700, Ian Wells wrote: 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. It is also not an unallowed change (given that there's a section that appears to define what an unallowed attribute change is). The page reads very awkwardly. Whatever your preference might be, I think it's best we lose the ambiguity. And perhaps advertise that page a little more widely, actually - I hadn't come across it in my travels. And perhaps improve its air of authority: rules on this subject should probably live somewhere in a repo so that it's clear there's consensus for changes. Currently anyone can change it for any reason, and two years after the last substantive change it's hard to say who even knew it was being changed, let alone whether they agreed. Such a repo exists! [1] You can see those docs rendered here. [2] It’s under the purview of the API Working Group. [3] You’re most welcome to join us. That APIChangeGuidelines wiki page really needs to be incorporated into the official repo [1]. I’ve added that as an agenda item to our next meeting on Thursday 2015-04-23 at 00:00 UTC [4]. [1] http://git.openstack.org/cgit/openstack/api-wg/ [2] http://specs.openstack.org/openstack/api-wg/ [3] https://wiki.openstack.org/wiki/API_Working_Group [4] https://wiki.openstack.org/wiki/Meetings/API-WG __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Minor changes to API
On Apr 20, 2015, at 2:19 PM, Douglas Mendizabal douglas.mendiza...@rackspace.commailto:douglas.mendiza...@rackspace.com wrote: Hi openstack-dev@ I was wondering if the API Working Group had an opinion on how to deal with minor changes to the api? For example, what if you wanted to add a new attribute to a JSON response? I would think that a minor change like that could be done without having to create a new versioned endpoint. So a newer release would just add the new attribute without having to create a new /v1.1/ endpoint. I’d suggest (like others have already) doing microversions like Nova [1]. Creating a new endpoint would be a cruel thing to do to your clients, especially considering it’s a seemingly backwards compatible change. 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. And let us not forget statically typed languages. But even there adding a new attribute isn’t that big of a deal. If there’s an unexpected attribute in a response, it can simply be ignored. No harm done. But the user might not even be aware the new attribute is available unless they’re not looking at their request/response logs. Hence the need for microversions. Everett [1] http://specs.openstack.org/openstack/nova-specs/specs/kilo/implemented/api-microversions.html __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Minor changes to API
On 20 April 2015 at 13:02, Kevin L. Mitchell kevin.mitch...@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. -- Ian. __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Minor changes to API
On Mon, Apr 20, 2015 at 03:10:40PM -0700, Ian Wells wrote: On 20 April 2015 at 13:02, Kevin L. Mitchell kevin.mitch...@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 pgpgK3_wSwOQj.pgp Description: PGP signature __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Minor changes to API
On 20 April 2015 at 15:23, Matthew Treinish mtrein...@kortar.org wrote: On Mon, Apr 20, 2015 at 03:10:40PM -0700, Ian Wells wrote: 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. It is also not an unallowed change (given that there's a section that appears to define what an unallowed attribute change is). The page reads very awkwardly. Whatever your preference might be, I think it's best we lose the ambiguity. And perhaps advertise that page a little more widely, actually - I hadn't come across it in my travels. And perhaps improve its air of authority: rules on this subject should probably live somewhere in a repo so that it's clear there's consensus for changes. Currently anyone can change it for any reason, and two years after the last substantive change it's hard to say who even knew it was being changed, let alone whether they agreed. 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. I appreciate your point and I'd be happy for that to be more obviously our position. The issue that the MTU change hit was the conflict between this general principle and the consensus in its project. Neutron's core team was giving a strong 'no more extensions' vibe at the last summit, Neutron hasn't got microversioning, and the content of that document is two years old and apparently not very widely known by reviewers as well as me. No choice would have been right. So again, how about we fix that document up and put it somewhere where it receives a bit more control and attention? -- Ian. __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
[openstack-dev] [api] Minor changes to API
Hi openstack-dev@ I was wondering if the API Working Group had an opinion on how to deal with minor changes to the api? For example, what if you wanted to add a new attribute to a JSON response? I would think that a minor change like that could be done without having to create a new versioned endpoint. So a newer release would just add the new attribute without having to create a new /v1.1/ endpoint. 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. Thanks, Douglas Mendizabal __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Minor changes to API
On 04/20/2015 01:19 PM, Douglas Mendizabal wrote: Hi openstack-dev@ I was wondering if the API Working Group had an opinion on how to deal with minor changes to the api? For example, what if you wanted to add a new attribute to a JSON response? I would think that a minor change like that could be done without having to create a new versioned endpoint. So a newer release would just add the new attribute without having to create a new /v1.1/ endpoint. 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? 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? That would put the onus on clients to explicitly grab the attributes that they're looking for, but that doesn't seem too crazy and it would simplify adding new attributes on the server side. You'd still need versioning to handle deleting attributes or changing their meaning, of course. Chris __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [api] Minor changes to API
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. 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. That would put the onus on clients to explicitly grab the attributes that they're looking for, but that doesn't seem too crazy and it would simplify adding new attributes on the server side. You'd still need versioning to handle deleting attributes or changing their meaning, of course. -- Kevin L. Mitchell kevin.mitch...@rackspace.com Rackspace __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
