> Finegrained versioning like that will quickly devolve into a thicket of
> differing versions that are very hard to pick apart.
>
> I'd much prefer an approach where the XML that is sent back is backwards
> compatible; that means that as versions progress, old clients will still
> find what they expect to see, though the XML may contain additional
> 'stuff' that old clients will just ignore.


Yep, David, versioning can be a bit of a quagmire.

The OSGi philosophy is to concede that change is just inevitable, even incompatible mods may be needed eventually, and to tackle this head-on with a well formed versioning model.

But of course you're right that in this particular case we could impose some constraints to simplify life a bit. Just thinking aloud, seems there are three options here (in order of decreasing flexibility):

1. Allow backward incompatible changes with a rev of the major version, e.g. on transitioning from 1.x to 2.x

2. Allow only backward compatible changes, which is the same as #1 except never incrementing the major version

3. Allow only forward compatible changes, which effectively boils down to adding a "void *" (e.g. an xsd:any in the XML case) to every type as the future extension point

Seems that option #1 is considered a bit OTT in this case.

The second option would work fine if we were sure that purely additive changes would always give sufficient flexibility, though of course it would still be useful for clients to specify the least version they require in an Accept header (with an implicit "or newer") so as to detect the case were a more up-to-date client that depends on a newly added element/attribute is invoking on an older server.

The third option seems a common approach, but its not quite the pancea if you get into ignoreUnknown/mustUnderstand semantics (again probably just an issue if there's a realistic case where a newer client may be invoking on an older server and needs to ensure that some aspect of the representation that its encoding in the extension point isn't just discarded on the server-side).

Cheers,
Eoghan

 
On 12 April 2010 23:44, David Lutterkort <lutter@redhat.com> wrote:
On Mon, 2010-04-12 at 23:20 +0100, Eoghan Glynn wrote:
>
> > The ability to bump the version in future if we really need to is
> what
> > most appeals to me e.g.
> >
> >  application/vnd.com.redhat.rhevm.api.VM+xml;version=1.1
>
>
> Yeah, I like the idea.
>
> We could even go nuts with the version property and allow a client
> specify a range in the Accept header, following the OSGi
> version-constraint pattern. Assuming it's implicit that only backward
> compatible changes are made to the schema types within a minor version
> rev.
>
> So suppose a client wanted to indicate it understands version 1.1 or
> later, but not anything in the 2.x line, it could express this
> constraint as:
>
>   Accept: application/vnd.com.redhat.rhevm.api.VM
> +xml;version=[1.1,2.0)

Finegrained versioning like that will quickly devolve into a thicket of
differing versions that are very hard to pick apart.

I'd much prefer an approach where the XML that is sent back is backwards
compatible; that means that as versions progress, old clients will still
find what they expect to see, though the XML may contain additional
'stuff' that old clients will just ignore.

David