On Wed, Aug 25, 2010 at 4:50 PM, Christoph Helma <helma at in-silico.ch> wrote:

> 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.
>


In fact this was my initial idea while on the plane to Boston :)  I had even
started some opentox-rest.owl.  But then saw the restlet WADL support and it
was lot easier to use existing XML schema than developing our own.

Both approaches are actually not mutually exclusive, we can generate OWL-DL
based on WADL ideas.

Best regards,
Nina


>
> Best regards,
> Christoph
> _______________________________________________
> Development mailing list
> Development at opentox.org
> http://www.opentox.org/mailman/listinfo/development
>



-- 

Dr. Nina Jeliazkova
Technical Manager
4 A.Kanchev str.
IdeaConsult Ltd.
1000 Sofia, Bulgaria
Phone: +359 886 802011