Open Stack

On Apr 20, 2015, at 2:19 PM, Douglas Mendizabal <douglas.mendizabal at RACKSPACE.COM<mailto:douglas.mendizabal at 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20150421/5becbb3d/attachment.html>