Excerpts from Nina Jeliazkova's message of Mon Aug 23 15:37:23 +0200 2010:
> 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.

My first impression is, that WADL gets little attention in the Ruby
community. With a quick search I have found no library that makes an
reliable impression. WADL seems to be also controversial in the
REST community (http://bitworking.org/news/193/Do-we-need-WADL). My
impression is that WADL is deeply rooted in Java culture, other cultures
would approach things differently ;-).

If it is about documentation, why don't we document in OWL-DL (e.g. in
analogy to algorithm respresentation)? This seems to be more consistent
with the rest of our framework.

Best regards,
Christoph