[rest-practices] Media types

[Eoghan Glynn]

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

Cheers,
Eoghan


On 15 April 2010 12:54, Mark McLoughlin <markmc at redhat.com> wrote:

> Hey,
>
> Okay, I'll take a shot at kicking this off
>
> We're beginning to work on defining a RESTful API for RHEV-M here:
>
>  https://fedorahosted.org/rhevm-api/
>
> One thing we're considering doing is adding new media types for the
> document formats produced and consumed by the API. Some discussion on
> that here:
>
>  https://fedorahosted.org/pipermail/rhevm-api/2010-April/000069.html
>
> The main motivation is that it gives us room to make an incompatible
> change in the document format and allow clients to negotiate which
> version they require
>
> To be clear - we're not planning on making incompatible changes, but
> it's best to design for the possibility
>
> So, the idea is to have e.g.
>
>  Accept: application/vnd.rht.rhevm.vm+xml;version=1
>
> We would only bump the version number if we make an incompatible change
> to the format. Clients would not be able to negotiate different
> compatible format versions
>
> Anyway, we should discuss:
>
>  - Whether this is a sound idea to adopt in general
>
>  - vnd.rht vs. vnd.redhat vs vnd.com.redhat
>
>  - Do we need to register these types with the IANA
>
>  - A single media type to describe all documents returned by the API:
>
>      application/vnd.rht.rhevm+xml;version=1
>
>    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
>
>  - Are modifiers like '+json' and '+yaml' standardised anywhere?
>
> Cheers,
> Mark.
>
> _______________________________________________
> rest-practices mailing list
> rest-practices at redhat.com
> https://www.redhat.com/mailman/listinfo/rest-practices
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/rest-practices/attachments/20100415/6d4c618e/attachment.htm>