Open Stack

On 02/16/2016 01:13 PM, Dean Troyer wrote:
> On Tue, Feb 16, 2016 at 8:34 AM, Andrew Laski <andrew at lascii.com
> <mailto:andrew at lascii.com>> wrote:
> ... 
> 
>      It's easy enough to think that users will just read the docs and
>     carefully consider every version increment that they want to consume
>     but when they've been on version 2.7 for a while and a new thing
>     comes out in 2.35 that they want they need to fully digest the
>     implications of all 27 intervening versions purely through docs and
>     with the understanding that literally almost anything about the
>     semantics can have changed. So while I love the freedom that it
>     provides to developers I think it would be useful to have a small
>     set of constraints in place that helps users. Of course all of my
>     ideas have been duds so far and perhaps that's because I'm imagining
>     future scenarios that won't come to pass or that we don't care
>     about. But something has me concerned and I can't quite get my
>     finger on it.
> 
> 
> Contrived example alert:
> 
> API version 2.10 adds a pile of parameters to POST /foo/.
> API version 2.35 fixes a problem in GET /bar/details.
> 
> As a client, I might need the 2.35 fix before I have finished
> implementing the big new feature in 2.10 (and intervening) changes.  The
> clients will then use the GLOBAL_API_VERSION=2.7 as a default and use a
> local 2.35 version for the /bar requests.
> 
> This may get fun to manage over time, but allows the client to opt-in to
> new API features without having to swallow the entire thing.  It also
> increases the pressure to make sure the docs are up to snuff for each
> specific API bump.

Honestly, doing per API call version switching is probably going to end
in tears. HTTP is stateless, so it's allowed, but it will end in tears
of complexity as you need to self modify resources before passing them
back. Or follow links that don't exist.

It's also worth looking at the changes we've actually been making here
instead of theoretical examples. The amount of effort to make an
application use 2.20 instead of 2.1 is pretty minimal.

	-Sean

-- 
Sean Dague
http://dague.net