OpenTox API 1.2 Dataset
Mrautenberg (Talk | contribs) (Created page with "<h2>REST operations</h2> {| <tbody> ! Description ! Method | <br> ! URI | <br> ! Parameters ! Result ! Status codes |- | Get a list of available datasets | GET | <br> | /datase...") |
Mrautenberg (Talk | contribs) |
||
(One intermediate revision by one user not shown) | |||
Line 130: | Line 130: | ||
<h3>Examples</h3><dl><dt>Get all features of two compounds</dt><dd><code>curl -X GET http://my_dataset_service/dataset_id?</code><code>compound_uris</code><code>[]=compound1_uri&</code><code>compound_uris</code><code>[]=compound2_uri</code></dd><dt>Get a single feature of a single compound</dt><dd><code>curl -X GET http://my_dataset_service/dataset_id?</code><code>compound_uris</code><code>[]=compound_uri&feature_uris[]=feature_uri</code></dd><dt>Remove a compound from a dataset</dt><dd><code>curl -X DELETE http://my_dataset_service/{dataset_id}?</code><code>compound_uris[]=<compound_uris></code></dd><dt>Upload an sdf to ambit server </dt><dd><code>curl -X POST -H 'Content-Type:chemical/x-mdl-sdfile' --data-binary @filename.sdf http://ambit.uni-plovdiv.bg:8080/ambit2/dataset</code></dd><dt>Get compound URIs of a dataset </dt><dd><code>curl -X GET -H 'Accept:text/uri-list' http://ambit.uni-plovdiv.bg:8080/ambit2/dataset/{dataset_id}</code></dd><dt>Upload an sdf that contains features of an already existing dataset (if a feature name in filename.sdf matches a feature name from associated_features the corresponding URI is assigned)</dt><dd><code>curl -X POST -H 'Content-Type:chemical/x-mdl-sdfile' --data-binary @filename.sdf -d 'associated_features=http://ambit.uni-plovdiv.bg:8080/ambit2/dataset/{datsaet_id}/feature' -d 'matcher=Name' http://ambit.uni-plovdiv.bg:8080/ambit2/dataset</code></dd></dl> | <h3>Examples</h3><dl><dt>Get all features of two compounds</dt><dd><code>curl -X GET http://my_dataset_service/dataset_id?</code><code>compound_uris</code><code>[]=compound1_uri&</code><code>compound_uris</code><code>[]=compound2_uri</code></dd><dt>Get a single feature of a single compound</dt><dd><code>curl -X GET http://my_dataset_service/dataset_id?</code><code>compound_uris</code><code>[]=compound_uri&feature_uris[]=feature_uri</code></dd><dt>Remove a compound from a dataset</dt><dd><code>curl -X DELETE http://my_dataset_service/{dataset_id}?</code><code>compound_uris[]=<compound_uris></code></dd><dt>Upload an sdf to ambit server </dt><dd><code>curl -X POST -H 'Content-Type:chemical/x-mdl-sdfile' --data-binary @filename.sdf http://ambit.uni-plovdiv.bg:8080/ambit2/dataset</code></dd><dt>Get compound URIs of a dataset </dt><dd><code>curl -X GET -H 'Accept:text/uri-list' http://ambit.uni-plovdiv.bg:8080/ambit2/dataset/{dataset_id}</code></dd><dt>Upload an sdf that contains features of an already existing dataset (if a feature name in filename.sdf matches a feature name from associated_features the corresponding URI is assigned)</dt><dd><code>curl -X POST -H 'Content-Type:chemical/x-mdl-sdfile' --data-binary @filename.sdf -d 'associated_features=http://ambit.uni-plovdiv.bg:8080/ambit2/dataset/{datsaet_id}/feature' -d 'matcher=Name' http://ambit.uni-plovdiv.bg:8080/ambit2/dataset</code></dd></dl> | ||
Together with a little bit of RDF processing you can use queries also for set operations (e.g. subsets, split, merge, intersection). | Together with a little bit of RDF processing you can use queries also for set operations (e.g. subsets, split, merge, intersection). | ||
− | <p><em>PS Take care to URI encode parameters that are sent via GET.</em></p><h2>Dataset representation</h2><h3>RDF specification</h3><h4>Metadata</h4><ul><li> | + | <p><em>PS Take care to URI encode parameters that are sent via GET.</em></p><h2>Dataset representation</h2><h3>RDF specification</h3><h4>Metadata</h4><ul><li>[http://opentox.org/data/documents/development/RDF%20files/Dataset RDF dataset representation] (Dublin core properties + [http://purl.org/dc/terms/license purl.org/dc/terms/license] and [http://purl.org/dc/terms/rightsHolder purl.org/dc/terms/rightsHolder] from Dublin Core terms ontology)</li><li>Web form (application/www-form-urlencoded) - parameter names is the name of the DC/DCterms property - e.g. <strong>title</strong> for <strong>dc:title</strong> , <strong>license</strong> for <strong>dcterms:license</strong> [http://www.w3.org/TR/2011/NOTE-void-20110303/" http://www.w3.org/TR/2011/NOTE-void-20110303/]. (<span class="visualHighlight">fully qualified names are rather inconvenient - is it sufficient to use just names?</span>)<br></li><li><em>Content-type:multipart/form-data </em><em>F</em>ile upload metadata: parameters as in opentox.owl - verify if fully qualified dc: properties can be used as parameter names (same as for Web form)<br></li></ul><h4>Features</h4><p> [http://opentox.org/data/documents/development/RDF%20files/Dataset RDF dataset representation]</p><p>The feature URI points to a [http://opentox.org/dev/apis/api-1.2/Feature Feature] object, which allows retrieval of the Feature object as RDF and provides information about the name, units, source and the type of the feature. The feature type is denoted by a mandatory link to an ontology via owl:sameAs or directly subclassing a class from an ontology.</p><p>This allows Feature URI to point directly to an existing (fixed) ontology, or to a web service, providing access to dynamically created Feature objects.</p><h4>Conformers</h4> |
Conformer URIs (see Compound API) can be used instead of compound URIs. The Resolving the parent structure should be done via the compound webservice. | Conformer URIs (see Compound API) can be used instead of compound URIs. The Resolving the parent structure should be done via the compound webservice. | ||
<h3>Examples</h3> | <h3>Examples</h3> |
Latest revision as of 12:15, 28 October 2013
Contents |
REST operations
Description | Method | |
URI | |
Parameters | Result | Status codes | ||
---|---|---|---|---|---|---|---|---|---|
Get a list of available datasets | GET | |
/dataset | |
[subjectid] Query parameters (optional, to be defined by service providers) |
List of URIs or RDF for the metadata only |
200,404,503 | ||
Get a dataset | GET | |
/dataset/{id} | |
[subjectid] | Representation of the dataset in a supported MIME type | 200,404,503 | ||
Query a dataset | GET | |
/dataset/{id} | |
[subjectid] compound_uris[] and/or feature_uris[] to select compounds and features; further query parameters may be defined by service providers |
Representation of the query result in a supported MIME type | 200,404,503 | ||
Get metadata for a dataset | GET | |
/dataset/{id}/metadata | |
[subjectid] | Representation of the dataset metadata in a supported MIME type | 200,404,503 | ||
Update metadata for a dataset | PUT |
|
/dataset/{id}/metadata |
|
[subjectid] |
RDF or application/www-form-urlencoded |
| ||
Get a list of all compounds in a dataset | GET | |
/dataset/{id}/compounds | |
[subjectid] | List of compound URIs | 200,404,503 | ||
Get a list of all features in a dataset | GET | |
/dataset/{id}/features | |
[subjectid] | RDF or List of feature URIs (pointing to feature definitions/ontologies) | 200,404,503 | ||
Create a new dataset | POST | |
/dataset | |
Dataset representation in a supported MIME type. MIME type to be specified via Content-type header.
[subjectid] |
<a title="Task" class="internal-link" href="AsyncTask#creating-a-task-post">New URI /dataset/{id} or redirect to task URI (for large uploads)</a> |
200,202,400,503 | ||
|
POST |
|
/dataset |
|
File upload via Content-type:multipart/form-data: file parameter Reference featureURI list (http://server/path/dataset/{dataset_id}/feature) Matcher (e.g. name of feature) |
<a title="Task" class="internal-link" href="AsyncTask#creating-a-task-post">New URI /dataset/{id} or redirect to task URI (for large uploads)</a> | 200,202,400,503 | ||
Update a dataset | PUT | |
|
|
|
<a title="Task" class="internal-link" href="AsyncTask#creating-a-task-post">Dataset URI or task URI</a> |
200,202,400,404,503 | ||
Remove a dataset | DELETE | |
/dataset/{id} | |
[subjectid] | - | 200,404,503 | ||
Remove a part of the dataset | DELETE | |
/dataset/{id} | |
compound_uris[] and/or feature_uris[]; further query parameters may be defined to select the data to be deleted [subjectid] |
- | 200,404,503</tbody> |
- subjectid (optional) parameter that contains the OpenSSO A&A token needed to access protected services.
Queries
Subsets of a dataset (e.g. all data for a certain feature, all data for a set of compounds)) are accessed through query parameters. This allows us to pass full URIs as parameters and circumvents the problem of no-unique IDs (e.g. for /dataset/{id}/compound/{compound_id} URIs). The query parameters compound_uris[] and feature_uris[] are mandatory, more advanced queries (e.g. similarity searches) may be implemented by individual services.
Examples
- Get all features of two compounds</dt>
curl -X GET http://my_dataset_service/dataset_id?
compound_uris
[]=compound1_uri&
compound_uris
[]=compound2_uri
</dd>- Get a single feature of a single compound</dt>
curl -X GET http://my_dataset_service/dataset_id?
compound_uris
[]=compound_uri&feature_uris[]=feature_uri
</dd>- Remove a compound from a dataset</dt>
curl -X DELETE http://my_dataset_service/{dataset_id}?
compound_uris[]=<compound_uris>
</dd>- Upload an sdf to ambit server </dt>
curl -X POST -H 'Content-Type:chemical/x-mdl-sdfile' --data-binary @filename.sdf http://ambit.uni-plovdiv.bg:8080/ambit2/dataset
</dd>- Get compound URIs of a dataset </dt>
curl -X GET -H 'Accept:text/uri-list' http://ambit.uni-plovdiv.bg:8080/ambit2/dataset/{dataset_id}
</dd>- Upload an sdf that contains features of an already existing dataset (if a feature name in filename.sdf matches a feature name from associated_features the corresponding URI is assigned)</dt>
curl -X POST -H 'Content-Type:chemical/x-mdl-sdfile' --data-binary @filename.sdf -d 'associated_features=http://ambit.uni-plovdiv.bg:8080/ambit2/dataset/{datsaet_id}/feature' -d 'matcher=Name' http://ambit.uni-plovdiv.bg:8080/ambit2/dataset
</dd>
Together with a little bit of RDF processing you can use queries also for set operations (e.g. subsets, split, merge, intersection).
PS Take care to URI encode parameters that are sent via GET.
Dataset representation
RDF specification
Metadata
- RDF dataset representation (Dublin core properties + purl.org/dc/terms/license and purl.org/dc/terms/rightsHolder from Dublin Core terms ontology)
- Web form (application/www-form-urlencoded) - parameter names is the name of the DC/DCterms property - e.g. title for dc:title , license for dcterms:license " http://www.w3.org/TR/2011/NOTE-void-20110303/. (fully qualified names are rather inconvenient - is it sufficient to use just names?)
- Content-type:multipart/form-data File upload metadata: parameters as in opentox.owl - verify if fully qualified dc: properties can be used as parameter names (same as for Web form)
Features
The feature URI points to a Feature object, which allows retrieval of the Feature object as RDF and provides information about the name, units, source and the type of the feature. The feature type is denoted by a mandatory link to an ontology via owl:sameAs or directly subclassing a class from an ontology.
This allows Feature URI to point directly to an existing (fixed) ontology, or to a web service, providing access to dynamically created Feature objects.
Conformers
Conformer URIs (see Compound API) can be used instead of compound URIs. The Resolving the parent structure should be done via the compound webservice.
Examples
Multi Cell Call prediction from J48 (N3 notation):
example:DatasetPredicted a ot:Dataset ; dc:identifier "http://myservice/dataset/{datasetid}"^^xsd:string ; dc:title "Multi Cell Call prediction from J48"^^xsd:string ; ot:dataEntry [ a ot:DataEntry ; ot:compound example:benzene ; ot:values [ a ot:FeatureValue ; ot:feature example:MultiCellCallPredicted ; ot:value "true"^^xsd:boolean ]; ot:values [ a ot:FeatureValue ; ot:feature example:MultiCellCall ; ot:value "true"^^xsd:boolean ] ; ] . example:benzene a ot:Compound ; dc:identifier "http://myservice/compound/{compoundid1}"^^xsd:string . example:MultiCellCallPredicted a ot:Feature ; dc:identifier "http://myservice/feature/{featureid3}"^^xsd:string ; dc:title "MultiCellCall"^^xsd:string ; ot:hasSource example:WekaJ48 .
Single compound with a single substructure:
<https://ambit.uni-plovdiv.bg:8443/ambit2/dataset/2407> a ot:Dataset ; ot:dataEntry [ a ot:DataEntry ; ot:compound <https://ambit.uni-plovdiv.bg:8443/ambit2/compound/17285> ; ot:values [ a ot:FeatureValue ; ot:feature <https://ambit.uni-plovdiv.bg:8443/ambit2/feature/171898> ; ot:value "true"^^xsd:boolean ] ] . <https://ambit.uni-plovdiv.bg:8443/ambit2/compound/17285> a ot:Compound . <https://ambit.uni-plovdiv.bg:8443/ambit2/feature/171898> a ot:Substructure ; dc:title "FCF" ; ot:smarts "FCF" ; ot:hasSource <https://ambit.uni-plovdiv.bg:8443/ambit2/model/26469> ; ot:Substructure a owl:Class ; rdfs:subClassOf ot:Feature .
Retrieving metadata:
curl -H "Accept:text/n3" <a href="http://apps.ideaconsult.net:8080/ambit2/dataset/1/metadata" target="_blank">http://apps.ideaconsult.net:8080/ambit2/dataset/112/metadata</a><<a href="http://apps.ideaconsult.net:8080/ambit2/dataset/112" target="_blank">http://apps.ideaconsult.net:8080/ambit2/dataset/112</a>> a ot:Dataset ; dc:title "ToxCast_ToxRefDB_20091214.txt" ;
dcterms:license <<a href="http://www.opendatacommons.org/licenses/pddl" target="_blank">http://www.opendatacommons.org/licenses/pddl></a> .
Adding metadata to an existing dataset (using RDF)
curl -X PUT -H "Content-type:application/rdf+xml" -d @mymetadata.rdf http://host/dataset/{id}/metadata
Adding metadata to an existing dataset (using web form)
curl -X PUT -d "license=<a href="http://www.opendatacommons.org/licenses/pddl" target="_blank">http://www.opendatacommons.org/licenses/pddl</a>" -d "title=blabla" <a href="http://host/dataset/%7Bid%7D/metadata" target="_blank">http://host/dataset/{id}/metadata</a>
Specifying the metadata on upload (mimics sending a multipart web form)
curl -X POST -F "file=@alkanes.csv"-F "license=<a href="http://www.opendatacommons.org/licenses/pddl/" target="_blank">http://www.opendatacommons.org/licenses/pddl/</a>"
-F "title=Alkanes" <a href="http://host/dataset/" target="_blank">http://host/dataset/</a>
Supported MIME types
Mandatory
- application/rdf+xml (default)
- application/www-form-urlencoded
- multipart/form-data
- <a name="idx-multipartform-data-1"></a>
Optional
- other RDF serialization formats
- application/xml
- text/xml
- text/x-yaml
- text/x-json
- application/json
- text/csv
- text/arff
- text/html
- chemical/x-mdl-sdfile
- ...
- multipart/form-data for file uploads
HTTP status codes
Interpretation | Nr | Name |
---|---|---|
Success | 200 | OK |
Asynchronous task started |
202 | Accepted |
Dataset not found | 404 | Not Found |
Incorrect MIME type | 400 | Bad request |
Service not available | 503 | Service unavailable</tbody> |