[rest-practices] Media types

Daniel Veillard veillard at redhat.com
Fri Apr 16 08:51:12 UTC 2010


On Thu, Apr 15, 2010 at 08:44:57AM -0400, Bill Burke wrote:
> Bryan Kearney wrote:
> >On 04/15/2010 08:21 AM, Eoghan Glynn wrote:

> >Is media type the preferred model for versioning rather than URL?
> >I could also see /v1/xxxx and /v2/xxxx as means of supporting
> >incompatible versions.
> >
> 
> What I've read is that a different URL scheme might be preferable
> for clients that are not able to participate in HTTP content
> negotiation (like a browser).  If you're following the guideline of

  I chime in a bit late, sorry.
Agreed, I don't think that the media type is really the right place to
carry versioning informations. Even when trying to content negociate
this will just confuse the intermediaries. Extra HTTP headers might work
(after all it's how your browser tells the server about language options
and supported image format).
But I tent to think that content negociation makes things way harder
(and fragile) than they should. A versioned URI space if you really want
to decouple different version support is the simplest IMHO.

> not exposing your URL schemes and instead using links, then things
> actually become simpler for the client as it doesn't have to set any
> Accept headers.
> 
> Another guideline you might want to adopt is to make XML schemas
> backward and forward compatible.  What does this mean?
> 
> 1) Do not remove XML types or fragments from new versions
> 2) Allow for *any* new XML elements or attributes in all your XML
> types.  This allows new versions that add new elements to be
> validated with older schemas.
> 3) Make any new attributes or elements optional.
> 
> IMO, there is really no downside to this approach.  XML you do not
> understand you can just ignore.

  That's the alternative to versionned URI space, though I would not
express that in terms of schemas [1], but in terms of code. Basically
the code picks the informations it knows about from the received data
and ignores the rest. That how we handle XML parsing in libvirt so far,
but there is a danger there, a missing part may change the semantic a
lot.
  To give an specific example we added at some point an extra cache=""
attribute to a disk definition of a vm, defining the caching policy,
and a client expecting cache="none" to ensure say database data
integrity in case of failure may be fooled into believing the server
actually accepted and understood that policy, possibly leading to
data corruption in case of vm crash.
  In practice it really worked well for us, but to some extent our
stack is a bit more controlled than in a pure web service framework.
So if going that route, then more care must be taken when defining
evolutions of the XML format.

  An intermediate way is to allow only unknow attributes on the received
XML but not unknown elements, such a generic policy allow to build
explicitely compatible and incompatible evolutions with a rather trivial
check on the receiving code.

Daniel

[1] I'm ready to argue about pros and cons of schemas and where they
    make sense but I'm afraid this can get boring really fast and also
    off-topic :-)

-- 
Daniel Veillard      | libxml Gnome XML XSLT toolkit  http://xmlsoft.org/
daniel at veillard.com  | Rpmfind RPM search engine http://rpmfind.net/
http://veillard.com/ | virtualization library  http://libvirt.org/




More information about the rest-practices mailing list