[rest-practices] Media types

[Mark McLoughlin]

On Thu, 2010-04-15 at 08:44 -0400, Bill Burke wrote:
> 
> Bryan Kearney wrote:
> > On 04/15/2010 08:21 AM, Eoghan Glynn wrote:
> >>
> >>
> >>  > A single media type to describe all documents returned by the API
> >>
> >> Interesting question.
> >>
> >> My initial reaction is that the single
> >> application/vnd.com.redhat.rhevm.api+xml media type may indeed be better
> >> than a proliferation of more fine-grained types, as really what we're
> >> trying to capture here is the "application protocol", which could be
> >> thought of in a holistic sense as applying to the entire API.
> >>
> >> Whereas the individual fine-grained type could be inferred from the
> >> entity-body in any case, from say the schema identified in the root
> >> xmlns attribute or whatever. So this doesn't need to be necessarily
> >> specified in the Content-Type header.
> >>
> >> A single media type may well be easier to standardize also, if we ever
> >> need to evolve it out of the vendor-private space.
> >>
> > 
> > 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 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.

That works for me

Basically, then, version negotiation is done by the client choosing
between e.g.

  <link rel="vms" href="...." />
  <link rel="vms_v2" href="..." />

Which reminds me:

  http://tools.ietf.org/html/draft-nottingham-http-link-header-09#section-4.2

  Applications that don't wish to register a relation type can use an
  extension relation type, which is a URI [RFC3986] that uniquely
  identifies the relation type.

So, rather than defining our own custom relation types as strings, we
should have a registry of relation types and identify them using URIs?

> 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.

OTOH, though, that means the validator won't catch even simple typos
like <link hrfe="..."/> which makes the validator rather less useful?

How do you imagine clients using the schema?

Just chatting with the libvirt guys (DV and danpb) about their schema
and they really only see the schema as useful in a client app's unit
test suite in order to validate the output of its XML generator

i.e. a client app wouldn't use it to validate the XML returned from
libvirt, because there's not much the app could do about a validation
failure

...
>  >   - Are modifiers like '+json' and '+yaml' standardised anywhere?
> 
> No, but IMO, they should be used.

btw, RESTeasy's yaml provider needs e.g. @Produces("application/*+yaml")

Cheers,
Mark.