> 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 <div class="gmail_quote">On 15 April 2010 12:54, Mark McLoughlin <<a href="mailto:markmc@redhat.com">markmc@redhat.com</a>> wrote: <blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">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: <a href="https://fedorahosted.org/rhevm-api/" target="_blank">https://fedorahosted.org/rhevm-api/</a> 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: <a href="https://fedorahosted.org/pipermail/rhevm-api/2010-April/000069.html" target="_blank">https://fedorahosted.org/pipermail/rhevm-api/2010-April/000069.html</a> 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 <a href="mailto:rest-practices@redhat.com">rest-practices@redhat.com</a> <a href="https://www.redhat.com/mailman/listinfo/rest-practices" target="_blank">https://www.redhat.com/mailman/listinfo/rest-practices</a> </blockquote></div>