Hi Nina, 
  This is very interesting and is also supported  by Restlet as you also
pointed out so I think we should give it a try!

Best regards,
Pantelis

On Mon, 2010-08-23 at 16:37 +0300, Nina Jeliazkova wrote:

> 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
> _______________________________________________
> Development mailing list
> Development at opentox.org
> http://www.opentox.org/mailman/listinfo/development
>