[rest-practices] Media types

[Bill Burke]

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.

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.

 >   - Do we need to register these types with the IANA
 >

IMO, wait until you're a bit more mature.

 >   - A single media type to describe all documents returned by the API:
 >
 >       application/vnd.rht.rhevm+xml;version=1
 >

You may find that you want more media types to be more explicit to the 
client of what you are expecting.  For example, if you want to use 
PATCH, your own microformats might be preferred:

http://www.subbu.org/blog/2010/04/using-patch

Although I personally will probably never use patch:

http://bill.burkecentral.com/2010/04/01/links-instead-of-patch
I've never liked the idea of having to look into a body of a message to 
figure out how to process it.  This might be important down the road if 
you need an intermediary that is a transformation engine.

 >     or a media type for each entity type:
 >
 >       application/vnd.rht.rhevm.vm+xml;version=1
 >       application/vnd.rht.rhevm.host+xml;version=1
 >       application/vnd.rht.rhevm.collection+xml;version=1
 >
 >     or also add media types for each collection type:
 >
 >       application/vnd.rht.rhevm.vm+xml;version=1
 >       application/vnd.rht.rhevm.host+xml;version=1
 >       application/vnd.rht.rhevm.collection.vm+xml;version=1
 >       application/vnd.rht.rhevm.collection.host+xml;version=1
 >

IMO, the above two are ok.  Atom does it!

applicatoin/atom+xml
application/atomcat+xml
application/atomsvc+xml

 >   - Are modifiers like '+json' and '+yaml' standardised anywhere?

No, but IMO, they should be used.

-- 
Bill Burke
JBoss, a division of Red Hat
http://bill.burkecentral.com