On Fri, 2010-04-16 at 10:28 +0200, Daniel Veillard wrote:
On Fri, Apr 16, 2010 at 08:13:46AM +0100, Mark McLoughlin wrote:
> On Thu, 2010-04-15 at 12:57 +0100, Mark McLoughlin wrote:
> > Hey,
> >
> > I've pushed a work-in-progress patch to add custom media types:
> >
> >
http://git.fedorahosted.org/git/?p=rhevm-api.git;a=commitdiff;h=2d9245e6ac
> >
> > and started a discussion on rest-practices about whether this is a good
> > idea:
> >
> >
https://www.redhat.com/archives/rest-practices/2010-April/msg00004.html
>
> My take away from that discussion is we don't need media types to do
> versioning, but instead we can add to the top-level API entry:
>
> <link rel="vms" href="...." />
> <link rel="vms_v2" href="..." />
>
> Given that adding a media type makes things slightly harder for the
> client and gives us extra headaches, I think we should drop the idea.
In general media-type doesn't seems the right place to handle versioning.
For XML syntaxes this is usually carried as a version attribute on the
top level element. Other options like using XML namespace for
versionning have been tried but this get painful in the implementations.
So I really suggest a top level attribute if you want to carry version
informations.
Just to be clear - what we're talking about here is how (in the
undesirable case where we make an incompatible change to format) the
client can request the older compatible version of the format
The in case the client doesn't know that version there is a
couple of
approaches possible:
1/ the liberal one: parse what you understand and ignore what you don't
know about, this makes the code way simpler, we followed that
approach in libvirt XML handling. It can be considered weak since
a missing piece of information can dramatically change the semantic
of the information, and there is no warning back at the software
level. In practice it worked for us so far but our stack is more
controlled than for pure web service. So if going there extra
attention must be provided when the XML evolves.
Right, this is the approach we'll take for all compatible changes to the
format
2/ content negociation: client receiving for example v2 but knowing
only v1 could negociate with the server, but this requires some
state saved on the server side about this specific client. This
really makes things more complex.
Yeah, I'd prefer media types to this
3/ an separate URI space for each different versions, this might be
the cleanest from a design POV, the server side will be simpler than
with content negociation. But that to be designed in the URI space
from the start, so the decision must be taken now basically.
Prefixing all paths with a version level isn't that hard, at least
on the client side.
Right, this is the approach we'll take if we ever make an incompatible
change to the format
Since we hope to never make an incompatible change, then there's no real
need to include a version number from the start e.g. initially we have:
HEAD / HTTP/1.1
HTTP/1.1 200 OK
Link: <http://{host}/hosts>; rel=hosts; type=application/xml
Link: <http://{host}/vms>; rel=vms; type=application/xml
Content-Length: 0
and if we make an incompatible change to the vms format, we can just do:
HEAD / HTTP/1.1
HTTP/1.1 200 OK
Link: <http://{host}/hosts>; rel=hosts; type=application/xml
Link: <http://{host}/vms>; rel=vms; type=application/xml
Link: <http://{host}/v2/vms>; rel=vms.v2; type=application/xml
Content-Length: 0
I would suggest 1/ or 3/ but the later has a strong impact, so the
decision should probably be taken early on.
I guess what we're looking at is a mixture of (1) and (3) - makes sense?
Thanks,
Mark.