From ToxBank API Wiki

(Difference between revisions)

Revision as of 15:39, 6 December 2011

Investigation

Investigations/Studies/Assays are modeled according to ISA-TAB standards

Investigation

High level concept to link related studies. Investigations are created by submitting ISA-TAB files.

A Investigation may have versions, which are Investigations that are linked to their predecessor.

Get a list of investigations

Description	Get a list of all investigations
Resource	Investigation
Method	GET
URI	/investigation
Parameters
Header Parameters	Accept:text/uri-list, application/rdf+xml subjectid:SECURITY-TOKEN
Media Type (input)
Results	List of investigations
Media Type (output)	text/uri-list, application/rdf+xml
Status code	200, 400

Description	Get a list of user related investigations
Resource	Investigation
Method	GET
URI	/investigation
Parameters
Header Parameters	User:USER_URI subjectid:SECURITY-TOKEN
Media Type (input)	Accept:application/rdf+xml, application/json, text/uri-list
Results	list of investigations owned/uploaded by a specific user
Media Type (output)	application/rdf+xml, application/json, text/uri-list
Status code	200, 400

Links: Page, Edit with form

Query all investigations

Description	Query all investigations with SPARQL
Resource	Investigation
Method	GET
URI	/investigation
Parameters	query
Header Parameters	Accept: one of text/plain (n-triples), text/turtle, application/rdf+xml (for CONSTRUCT queries), subjectid:SECURITY-TOKEN
Media Type (input)
Results	Query result
Media Type (output)	application/sparql-results+xml (SELECT queries), text/plain (n-triples), text/turtle, application/rdf+xml (CONSTRUCT queries)
Status code	200

Links: Page, Edit with form

Create an investigation

Description	Create a new investigation from ISA-TAB files
Resource	Investigation
Method	POST
URI	/investigation
Parameters	optional params: allowReadByUser: one or multiple userservice-URIs (User) allowReadByGroup: one or multiple userservice-URIs (Organisations, Projects) summarySearchable: true/false (default is false) required params (when upload not in isa-tab format): type: one of noData/unformattedData/ftpData title: string abstract: string owningOrg: one userservice-URI (Organisations) owningPro: one or multiple userservice-URIs (Projects) authors: one or multiple userservice-URIs (User) keywords: one or multiple owl-URIs ftpFile: one or multiple filenames (only for type ftpData) optional params (when upload not in isa-tab format): licenses: string
Header Parameters	subjectid:SECURITY-TOKEN
Media Type (input)	multipart/form-data: upload ISA-TAB files (isa-tab zip archive) upload unformatted data (zip archive, required params) upload without data (ftp filename, required params) upload without data (required params)
Results	Task URI
Media Type (output)	text/uri-list
Status code	202, 400, 401

cURL example

curl -Lk -X POST -i -H "subjectid:MYTOKEN" -F file="@ExampleFilename.zip;type=application/zip" \
https://services.toxbank.net/investigation?allowReadByUser=USER_URI1,USER_URI2&allowReadByGroup=GROUP_URI1,GROUP_URI2&summarySearchable=VALUE

curl -Lk -X POST -i -H "subjectid:MYTOKEN" -d "type=noData" -d "title=STRING" -d "abstract=STRING" -d "owningOrg=GROUP_URI" \ 
-d owningPro=GROUP_URI1,GROUP_URI2" -d "authors=USER_URI1,USER_URI2" -d "keywords=OWL_URI1,OWL_URI2" -d "allowReadByUser=USER_URI1,USER_URI2" \
-d "allowReadByGroup=GROUP_URI1,GROUP_URI2" -d "summarySearchable=VALUE" https://services.toxbank.net/investigation

curl -Lk -X POST -i -H "subjectid:MYTOKEN" -F file="@ExampleFilename.zip;type=application/zip" \
https://services.toxbank.net/investigation?type=unformattedData&title=STRING&abstract=STRING&owningOrg=GROUP_URI&owningPro=GROUP_URI1,GROUP_URI2 \
&authors=USER_URI1,USER_URI2&keywords=OWL_URI1,OWL_URI2&allowReadByUser=USER_URI1,USER_URI2&allowReadByGroup=GROUP_URI1,GROUP_URI2 \
&summarySearchable=VALUE

curl -Lk -X POST -i -H "subjectid:MYTOKEN" -d "type=ftpData" -d "title=STRING" -d "abstract=STRING" -d "owningOrg=GROUP_URI" \
-d owningPro=GROUP_URI1,GROUP_URI2" -d "authors=USER_URI1,USER_URI2" -d "keywords=OWL_URI1,OWL_URI2" -d "licenses=STRING" \
-d "ftpFile=FILENAME_A,FILENAME_B" -d "allowReadByUser=USER_URI1,USER_URI2" -d "allowReadByGroup=GROUP_URI1,GROUP_URI2" \
-d "summarySearchable=VALUE" https://services.toxbank.net/investigation

Links: Page, Edit with form

Get an investigation

Description	Get an investigation representation
Resource	Investigation
Method	GET
URI	/investigation/{id}
Parameters
Header Parameters	Accept: one of text/tab-separated-values, text/uri-list, application/zip, text/plain (n-triples), text/turtle, application/rdf+xml, subjectid:SECURITY-TOKEN
Media Type (input)
Results	Investigation ISA-TAB file, list of study, assay and data URIs, zipped ISA-TAB files (including studies, assays and data files) or RDF representation
Media Type (output)	text/tab-separated-values, text/uri-list, application/zip, text/plain, application/rdf+xml
Status code	200, 400, 401, 404

Links: Page, Edit with form

Create a new version of an investigation

Description	Create a new version of an investigation
Resource	Investigation
Method	POST
URI	/investigation/{id}
Parameters
Header Parameters
Media Type (input)	multipart/form-data
Results	URI of new investigation version
Media Type (output)	text/uri-list
Status code

Will create a new investigation which is linked to the original investigation, the original investigation will remain intact Links: Page, Edit with form

Delete an investigation

Description	Delete an investigation
Resource	Investigation
Method	DELETE
URI	/investigation/{id}
Parameters
Header Parameters	subjectid:SECURITY-TOKEN
Media Type (input)
Results	Success message
Media Type (output)	text/plain
Status code	200, 401

Links: Page, Edit with form

Study

The central ISA-TAB unit containing information on the subjet under study, its characteristics and any treatments applied.

A Study has associated Assays, it is the result of executing a set of Protocols.

A Study has an Author (an User).

N3 representation of a study

<http://toxbank.net/services/study/Study_3>
     a       tb:Study ;
     tb:hasAbstract "This is an abstract"^^xsd:string ;
     tb:hasAssay http://toxbank.net/services/study/Study_3/assay/Assay_7> ;
     tb:hasAuthor tb:OliviaSanger ;
     tb:hasKeyword "abc"^^xsd:string ;
     tb:hasOwner tb:ORG5 ;
     tb:isSummarySearchable
             "true"^^xsd:boolean ;
     tb:project tb:DETECTIVE ;
     tb:versionInfo "1"^^xsd:string .

Get a list of studies of an investigation

Description	Get a list of studies
Resource	Investigation
Method	GET
URI	/investigation/{id}/study
Parameters
Header Parameters
Media Type (input)	none
Results	List of studies
Media Type (output)	text/uri-list
Status code	200,400,401,402,403

Links: Page, Edit with form

Add a new study to an investigation

Description	Add/update studies, assays or data to an investigation
Resource	Investigation
Method	PUT
URI	/investigation/{id}
Parameters	optional params: allowReadByUser: one or multiple userservice-URIs (User) allowReadByGroup: one or multiple userservice-URIs (Organisations, Projects) summarySearchable: true/false (default is false) published: true/false (default is false) required params (when upload not in isa-tab format): type: one of noData/unformattedData/ftpData title: string abstract: string owningOrg: one userservice-URI (Organisations) owningPro: one or multiple userservice-URIs (Projects) authors: one or multiple userservice-URIs (User) keywords: one or multiple owl-URIs ftpFile: one or multiple filenames (only for type ftpData)
Header Parameters	subjectid:SECURITY-TOKEN
Media Type (input)	multipart/form-data
Results	Task URI
Media Type (output)	text/uri-list
Status code	202, 400, 401, 423

Individual ISA-TAB files (text/tab-separated-values) or zip archives of study, assay and data files can be posted as form data to add files to an existing investigation. Investigations without ISA-TAB formated data can be edited by parameters and data files posted as form data replace existing data. Links: Page, Edit with form

Get a study representation

Description	Get a study, assay, data representation
Resource	Investigation
Method	GET
URI	/investigation/{id}/isatab/{filename}
Parameters
Header Parameters	subjectid:SECURITY-TOKEN
Media Type (input)
Results	Study, assay, data representation in ISA-TAB format
Media Type (output)	text/tab-separated-values
Status code	200, 400, 401, 404

Links: Page, Edit with form

Study versions

N3 representation of a Study with a previous version

<http://toxbank.net/services/study/Study_4>
     a       tb:Study ;
     tb:hasAbstract "This is another abstract"^^xsd:string ;
     tb:hasAssay http://toxbank.net/services/study/Study_4/assay/Assay_11> ;
     tb:hasAuthor tb:OliviaSanger ;
     tb:hasKeyword "cell"@en , "protein"@en ;
     tb:hasOwner tb:ORG5 ;
     tb:isSummarySearchable
             "true"^^xsd:boolean ;
     tb:project tb:DETECTIVE ;
     tb:studyPriorVersion
             <http://toxbank.net/services/study/Study_3>;
     tb:versionInfo "2"^^xsd:string .

Upload a new Study version

Description	Creates a new study version
Resource	Investigation
Method	POST
URI	/study/{id}/versions
Parameters	TBD, file content in multipart web form, with predefined metadata, or any supported representation
Header Parameters
Media Type (input)	multipart web form - application/x-www-form-urlencoded, RDF, JSON
Results	Task URI, when complete - URI of the new study , e.g. /study/S123
Media Type (output)	text/uri-list
Status code	200,400,401,402,403

Links: Page, Edit with form

Retrieve Versions of a single Study

Description	Retrieves the study versions
Resource	Study
Method	GET
URI	/study/{id}/versions
Parameters	TBD, search options to filter the requested versions
Header Parameters	SECURITY-TOKEN
Media Type (input)	none?
Results	Links to studies (representation in supported format)
Media Type (output)	URI,RDF,JSON,XML
Status code	200,400,401,402,403

Links: Page, Edit with form

Assays

Tests performed either on material taken from the subject or on the whole initial subject, which produce qualitative or quantitative measurements (data).

An Assay serves as a container, associating a Protocol with the generated data.

N3 representation of an Assay

 <http://toxbank.net/services/study/Study_3/assay/Assay_7>
     a       tb:Assay ;
     tb:hasData "http://abc.de/dataset/D123"^^xsd:anyURI ;
     tb:hasData "http://abc.de/dataset/D456"^^xsd:anyURI ;
     tb:hasProtocol <http://toxbank.net/services/protocol/Protocol_9> ;
     tb:isPartOfStudy <http://toxbank.net/services/study/Study_3>.

<http://toxbank.net/services/study/Study_4/assay/Assay_11>
     a       tb:Assay ;
     tb:hasData "http://my.com/dataset/mydataset"^^xsd:anyURI ;
     tb:hasProtocol <http://toxbank.net/services/protocol/Protocol_9> ;
     tb:isPartOfStudy
             <http://toxbank.net/services/study/Study_4>.

Retrieve all Assays

Description	Get a list of all assays in a study
Resource	Investigation
Method	GET
URI	/investigation/{id}/study/{id}/assay
Parameters
Header Parameters
Media Type (input)
Results	List of assay URIs
Media Type (output)	text/uri-list
Status code	200,400,401,402,403

Links: Page, Edit with form

Retrieve a single Assay

Description	Get an assay representation
Resource	Investigation
Method	GET
URI	/investigation/{id}/study/{id}/assay/{id}
Parameters
Header Parameters
Media Type (input)
Results	Assay representation in ISA-TAB or RDF format
Media Type (output)	text/tab-separated-values, application/sparql-results+json
Status code	200,400,401,402,403

Links: Page, Edit with form

Upload a single Assay

Description	Add an assay to a study
Resource	Investigation
Method	POST
URI	/investigation/{id}/study/{id}/assay
Parameters
Header Parameters
Media Type (input)	multipart/form-data
Results	URI of the new assay
Media Type (output)	text/uri-list
Status code	200,202,400,401,402,403

Assays should be submitted as attachment in ISA-TAB format (text/tab-separated-values). Links: Page, Edit with form

Retrieve a Protocol, associated with an Assay

Description	Get an assay representation
Resource	Investigation
Method	GET
URI	/investigation/{id}/study/{id}/assay/{id}
Parameters
Header Parameters
Media Type (input)
Results	Assay representation in ISA-TAB or RDF format
Media Type (output)	text/tab-separated-values, application/sparql-results+json
Status code	200,400,401,402,403

Links: Page, Edit with form

Retrieve Datasets, associated with an Assay

Description	Get all data associated with an assay
Resource	Investigation
Method	GET
URI	/investigation/{id}/study/{id}/assay/{id}/data
Parameters
Header Parameters
Media Type (input)
Results	Links to datasets
Media Type (output)	text/uri-list
Status code	200,400,401,402,403

Links: Page, Edit with form

Upload Assay Data

Description	Upload assay data
Resource	Investigation
Method	POST
URI	/investigation/{id}/study/{id}/assay/{id}/data
Parameters
Header Parameters
Media Type (input)	multipart/form-data
Results	URI of new dataset
Media Type (output)	text/uri-list
Status code	200,202,400,401,402,403

Upload data files in their native format (e.g. CEL files, ISA-TAB data). Links: Page, Edit with form

Facts about InvestigationRDF feed

@@ Line 60: / Line 60: @@
 {{HasOperation |id=API_Study:Retrieve}}
+<!--
 == Retrieve Metadata of a single Study ==
 {{HasOperation |id=API_Study:RetrieveMetadata}}
+-->
 = Study versions =

Acts on	Study +
HasOperation	API Investigation:List +, API Investigation:Query +, API Investigation:Create +, API Investigation:View +, API Investigation:Add +, API Investigation:Delete +, API Study:RetrieveList +, API Study:Upload +, API Study:Retrieve +, API Study:UploadVersion +, API Study:RetrieveVersions +, API Study:RetrieveStudyAssays +, API Study:RetrieveStudyAssay +, API Study:UploadStudyAssay +, API Study:RetrieveStudyData + and API Study:UploadAssayData +
Has output media type	URI,RDF,JSON,XML +
Has status code	200,400,401,402,403 +

Investigation

Revision as of 15:39, 6 December 2011

Contents

Investigation

Get a list of investigations

Query all investigations

Create an investigation

cURL example

Get an investigation

Create a new version of an investigation

Delete an investigation

Study

N3 representation of a study

Get a list of studies of an investigation

Add a new study to an investigation

Get a study representation

Study versions

N3 representation of a Study with a previous version

Upload a new Study version

Retrieve Versions of a single Study

Assays

N3 representation of an Assay

Retrieve all Assays

Retrieve a single Assay

Upload a single Assay

Retrieve a Protocol, associated with an Assay

Retrieve Datasets, associated with an Assay

Upload Assay Data

Views

Personal tools

Navigation

OpenTox API 1.2

ToxBank extensions

Search

Toolbox