Thanks Nina - this is quite useful

On Sep 1, 2010, at 3:21 AM, Nina Jeliazkova wrote:

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

----------------------------------------------------
Rajarshi Guha        | NIH Chemical Genomics Center
http://www.rguha.net | http://ncgc.nih.gov
----------------------------------------------------
Q:  What's polite and works for the phone company?
A:  A deferential operator.