Open Stack

On Wed, Feb 26, 2014 at 6:38 AM, Dan Smith <dms at danplanet.com> wrote:
>> We may need to differentiate between breaking the API and breaking
>> corner-case behavior.
>
> Totally agreed.
>
>> In one case you force everyone in the ecosystem to
>> adapt (the libraries, the end user code). In the other you only
>> (potentially) affect those that were not following the API correctly.
>
> The problem is that the API spec is too loose right now, which is
> definitely a problem. However, I think I'd much rather tighten things
> down and deal with the potential fallout of someone's client breaking
> and saying "oh, I thought 'red' was a valid uuid" than whole rewrites.

quietly changing things sounds like a recipe for upset users.  There
are two contracts that we produce every time we release an API:

* The specs we document
* The actual implementation and all of its bugs and quirks.

Users actually care about the latter. If the API accepts 'red' as a
valid UUID then that is part of the implicit contract.

If we do go down this route of changing the v2 API like this, it would
be nice to bump the minor version as well, so when a user has to
distinguish between the two versions they don't have to say Havana V2
vs Icehouse V2, they can just say v2.1.

So Either way we should rev some version number when making these
changes, so we don't surprise the end users.

>
>> We could make a V3 that doesn't break the API, only breaks behavior in
>> error cases due to its stronger input validation. A V3 that shouldn't
>> break code that was following the API, nor require heavy library
>> changes. It's still a major API bump because behavior may change and
>> some end users will be screwed in the process, but damage is more
>> limited, so V2 could go away after a shorter deprecation period.
>
> What's the difference between saying "/v2 will return a 404 after K" and
> saying "If your client doesn't declare support for revision 2 of these
> calls" we'll return a 405, 406, 410, etc? Actually, 412 seems to be
> exactly this case.
>
> --Dan
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev