Open Stack

On Mon, 24 Feb 2014 15:54:42 -0800
Morgan Fainberg <m at metacloud.com> wrote:

> Yes, micro-versioning is most likely a better approach, and I’m a fan
> of using that to gain the benefits of V3 without changing for the
> sake of change. Ideally in a versioned API we should be versioning a
> smaller surface area than “THE WHOLE API” if at all possible. If we
> kept the old “version” around and deprecated it (keep it for 2
> cycles, when it goes away the non-versioned call says “sorry, version
> unsupported”?, and it can continue to be versioned as needed) and
> continue to increment the versions as appropriate with changes, we
> will be holding true to our contract. The benefits of V3 can still be
> reaped, knowing where the API should move towards.

So we have a very large number of changes we want to make to the V2
API, and we've already done the work (including adding versioning to
make backwards compatible changes easier in the future) in the V3 API.

How is backporting all those changes to V2, marking the old behaviour as
deprecated and the removing them in 2 cycles (forcing them off the
old behaviour) any different from releasing the V3 API, marking the V2
as deprecated and removing it in the same timeframe? Except that the
former involves a lot more work?

Where there is compatibility between the V2 and V3 API the only change
which is required is the accessing it via /v3 instead of /v2/tenant_id

> don’t work for large surface area projects). I still stand by my
> statement that we can’t (shouldn’t knowingly) break the contract, we
> also can’t assume people will move to V3 (if we launch it) in a
> reasonable timeframe if the new API doesn’t really justify a massive
> re-write. 

If we can't assume people will make the changes to move to V3, then how
we can we assume they'll make the necessary changes with the
deprecation-in-place model when the amount of change required is
basically the same if we want to make the same improvements? 

Also in terms of consistency of the API we don't actually reap most of
the advantage until all of the changes have been made. Because until
that point we are still look like inconsistent API to users.

Chris