Open Stack

On Wed, 3 Aug 2016, Andrew Laski wrote:

> I am a fan of microversions. I think they work wonderfully to express
> when a resource representation changes, or when different data is
> required in a request. This allows clients to make the same request
> across multiple clouds and expect the exact same response format,
> assuming those clouds support that particular microversion. I also think
> they work well to express that a new resource is available. However I do
> think think they have some shortcomings in expressing that a resource
> has been removed. But in short I think microversions work great for
> expressing that there have been changes to the structure and format of
> the API.

Yeah.

microversions are effectively a locally created stand in for the pre-
existing concept of content negotiation (of versioned media-types) in
HTTP with some overloaded functionality and semantics. Where the
microversions functionality is aligned with content negotiation
(expressing differences in resource representations in requests and
responses) it works well enough as a control mechanism. Where it tries
to operate as a stand in for other aspects of HTTP it doesn't work as
well. For example, using a microversion to indicate the removal of a
resource is redundant. HTTP provides 404 and 410 (and sometimes things
in the 3xx range) for that. If client code is relaying that response to
the user agent, that's a pretty effective post hoc _signal_. There's no
good way to a priori signal the missing resources. Some initial action
is required by the client, whether that's pulling in some
capabilities[1] or simply reading some docs.

In the context of a removed resource all a microversion provides is a
mode of control (I want the old version so I can get at the old
thing), separate from any server->client signalling.

I think we can do a better job of treating and respecting users (end and
middle) as humans by having strong expectations on each side of the
equation that there will be human and humane communication about the
state of the API[2]. We persist in the belief that microversions are a
signal that gets straight to the actual user but it isn't really all
that clear that they are anywhere near as visible as that statement
would suggest. Nor, really, should they be. The behavior of the API
is the most visible thing.

As Jay says, we should encourage and vigorously require them to upgrade
(by raising the minimum version) and more importantly we should make it
worth their while. At the moment it seems like we make either make it
too easy for users and deployers to stay in the past[3] of
insufficiently desirable for them to upgrade.

[1] Mind you, capabilities feels like a bit like a locally created stand
in for hypermedia[2].

[2] Hypermedia may or may not be a myth.

[3] Of course at some point it needs to be true that an API is done
and other functionality should happen elsewhere.

-- 
Chris Dent               ┬─┬ノ( º _ ºノ)         http://anticdent.org/
freenode: cdent                                         tw: @anticdent