I guess WADL addresses more than just the media types, i.e. the HTTP verb, URI structure, response codes etc. If we're targeting consumption by humans as opposed to tooling, my feeling is that WADL may be a bit over the top. So I'd prefer to start with a traditional plain ol' English description of the interactions, combined with schemata for the request/response payloads. It can always be WADLized later on if there's a need.

Cheers,
Eoghan

On 5 April 2010 19:33, David Lutterkort <lutter@redhat.com> wrote:

I like that a lot - the remaining question then is how do you describe
all those media types ? I would actually lean towards not specifying a
MIME/media type (that can be taken care of with content negotiation
between client and server, so that the client can, e.g., choose between
an XML and json representation) and document the request and response
with some sort of schema:

 <link method="post" rel="reboot" schema="http://rhev-api.example.com/reboot-action" href="http://host.rhevm/vms/XXX/reboot"/>

Not sure what the right schema language is .. WADL ? Relax-NG for the
response, something free-form for the request ? Since the schema only
documents one representation (e.g., XML) it should be clear how to get
to the schema for another representation (in practice, only JSON)

Doing this for the entire API is a lot of work (and even more work to
keep in line with the implementation), so it'll only be worth it if
there are actually clients that pay attention to the schema - otherwise,
you might as well document it in plain old English as most of the REST
API's out there do today.

David


_______________________________________________
rhevm-api mailing list
rhevm-api@lists.fedorahosted.org
https://fedorahosted.org/mailman/listinfo/rhevm-api