All,

Related to  the efforts to improve the current documentation of OpenTox
API,  I would like to propose using WADL for documenting OpenTox REST
services.

WADL offers unified way of providing information about the resources,
methods, query parameters and return codes.  See
https://wadl.dev.java.net/wadl20061109.pdf .

This might be used in several ways :

1) Generate manually WADL description of services, according to the
documented API.  WADL has a relatively simple XML schema, it could be then
run trough XSLT to generate HTML / PDF for documentation.  This is best  to
be hosted on a version control system to easily track changes.

2) Services should provide WADL description of themselves , on -H
Accept:application/vnd.sun.wadl+xml

3) It could be used to automatically generate clients (similar to WSDL), but
this is outside of the scope of this proposal.

Implementation:  Restlet has straightforward support for WADL
http://wiki.restlet.org/docs_2.0/13-restlet/28-restlet/72-restlet.html .
Hope there are Ruby libraries as well.

Best regards,
Nina