[rest-practices] Media types

[Mark McLoughlin]

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.