Rajarshi, All,

While at eChemInfo workshop, I've started couple of documents that might
help

http://www.ideaconsult.net/downloads/echeminfo/OpenTox-exercises.pdf
http://www.ideaconsult.net/downloads/echeminfo/OpenTox-API.pdf



On Wed, Sep 1, 2010 at 10:07 AM, Barry Hardy <barry.hardy at douglasconnect.com
> wrote:

>  Dear All:
> - OpenTox API Development
> Proposals for updated version 1.2 of the OpenTox API should be submitted in
> coming days for discussion and potential incorporation into the next OpenTox
> API specification (to be completed this month)
> Draft pages are located at http://www.opentox.org/dev/apis/api-1.2 and
> require a login to the website to access and edit.
>
> - API & Developer Documentation
> Roman (cc'ed here)  is currently working on documenting "getting started"
> guidance for new service developers, which we should be starting to release
> on the OT web site this month. If you have run into an issue or solved it
> :), please let us know so it can be included.
>
> Rajarshi has reviewed the current API documentation
> http://www.opentox.org/dev/apis/api-1.1
> and provides the following feedback:
>
> Overall well documented API. The most obvious thing that jumps out is that
> there aren't examples for all URIs. Even simple URL's (for GET) or curl
> invocations (for POST) would be useful, if nothing else to look at the
> return values. (I see that some API pages such as the models page, have
> example URI's, but more would be nicer)
>
> The inclusion of examples would be helpful, when explaining some of the
> specific REST services. For example, in the chemical compound service, the
> "Get the representation of a compound", it's not clear from the API docs how
> feature_uris[] should be specified.


This is optional and specified via query parameters, e.g.
?feature_uris[]=...


> Where can I find a list of feature URI's?


List of features are available via GET operation on feature service , e.g.

curl -X GET http://apps.ideaconsult.net:8080/ambit2/feature



> And will all feature URI's specified somewhere be available for any OpenTox
> service that provides this API?
>
>
Feature uris are specific for the each feature service, and reflect uploaded
data, that's, they will be different set of features across different
feature services (similar to different algorithms, available via different
algorithm services)


> Similarly, when I search for compounds, examples of what the search
> parameter could be would be useful. Similarly for the "sameas" parameter.
>

There are some example in the documents cited above, but obviously not
sufficient.

>
> This becomes more useful for the Feature service - while I can understand
> what URL's to use to interact with the service I have no idea of what values
> I should be using for the parameters. Given that most of these services take
> RDF input, examples would be very useful, for a user who is not too familiar
> with RDF
>
> In the Conformers section of the compound services, does this refer to
> pre-calculated conformers?


Yes


> What would happen if I call "compound/{id1}/conformer/" and there are no
> conformers available? Will it return the structure itself?


All available structures.


> Will it generate a set of conformers?



No, generation might be done by a relevant algorithm.



> Under what conditions will a 404 and 503 be returned?
>
>
 404 - Not found
503 - internal server error

> @Developers - message is clear, we need to provide more concrete examples,
> linked but not scrambled with specs.
>
>
See documents above, no doubt they can be improved.

Best regards,
Nina


> Thanks for your contribution Rajarshi!
>
> Barry
> _______________________________________________
> Development mailing list
> Development at opentox.org
> http://www.opentox.org/mailman/listinfo/development
>