Revision as of 13:16, 14 December 2011 (view source) Nina (Talk | contribs) ← Older edit		Revision as of 14:07, 14 December 2011 (view source) Nina (Talk | contribs) m (→Retrieve the List of Protocols) Newer edit →
Line 23:		Line 23:
	== Retrieve the List of Protocols ==		== Retrieve the List of Protocols ==
	{{HasOperation |id=API_Protocol:RetrieveList}}		{{HasOperation |id=API_Protocol:RetrieveList}}
		+
		+	Example: [http://toxbanktest1.opentox.org:8080/toxbank/protocol http://toxbanktest1.opentox.org:8080/toxbank/protocol]
		+	=== cURL example ===
		+	curl -X GET -H 'Accept:text/uri-list' -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/protocol
		+
		+	curl -X GET -H 'Accept:application/rdf+xml' -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/protocol?search=Tox
		+
		+	curl -X GET -H 'Accept:text/uri-list' -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/protocol?page=0&pagesize=5
	== Upload a new Protocol ==		== Upload a new Protocol ==

---

Revision as of 14:07, 14 December 2011

Protocol

Contents 1 Content 1.1 Document 1.2 Data 1.3 Versions 1.4 Authors, Owners, Organisations, Project 2 REST interface 2.1 Retrieve the List of Protocols 2.1.1 cURL example 2.2 Upload a new Protocol 2.3 Retrieve Metadata of a single Protocol 2.4 Retrieve Protocol files 2.4.1 cURL example - retrieve the protocol in PDF and Word formats 3 Protocol versions 3.1 N3 representation of a Protocol with a previous version 3.2 Retrieve versions of a single Protocol 3.3 Upload a new Protocol version 4 Security 4.1 Only a Principal Investigator (PI) is allowed to upload protocols 4.1.1 Design 4.2 Protocol read rights are specified on upload, and can be modified later by the PI 4.2.1 Design 5 RDF representation

Content

Document

Protocols contain a single MSWord or PDF document, describing how to perform certain experiment (lab or in-silico), and metadata.

Data

A Protocol defines a Data template. The results of performing the experiment are recorded in a (set of) Investigations.

Versions

A Protocol may have versions. A Protocol version is another Protocol.

Authors, Owners, Organisations, Project

A Protocol includes links to Author(s), related Project and Organisation. The protocol Owner is assigned automatically, when the protocol is uploaded by a logged-in user.

TBD: Parameter names to be added to the protocol representation, as in ISA-TAB

REST interface

Retrieve the List of Protocols

Description	Retrieves list of protocols
Resource	Protocol
Method	GET
URI	/protocol
Parameters	none, or ?search=name or paging parameters: page, pagesize or modefiedSince=UNIX-TIME-STAMP-in-ms
Header Parameters	subjectid:SECURITY-TOKEN
Media Type (input)	none
Results	The protocol representation in supported media type
Media Type (output)	text/uri-list;application/rdf+xml;text/n3
Status code	200, 400, 401, 402, 403

Links: Page, Edit with form

Example: http://toxbanktest1.opentox.org:8080/toxbank/protocol

cURL example

curl -X GET -H 'Accept:text/uri-list' -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/protocol 

curl -X GET -H 'Accept:application/rdf+xml' -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/protocol?search=Tox

curl -X GET -H 'Accept:text/uri-list' -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/protocol?page=0&pagesize=5

Upload a new Protocol

Description	Uploads a protocol
Resource	Protocol
Method	POST
URI	/protocol
Parameters	(see cURL example)
Header Parameters	subjectid:SECURITY-TOKEN
Media Type (input)	multipart/form-data
Results	Task representation in supported MIME formats
Media Type (output)	text/uri-list;application/rdf+xml;text/n3
Status code	200,202,400,401,402,403,500

Links: Page, Edit with form

Retrieve Metadata of a single Protocol

Description	Retrieves the protocol metadata
Resource	Protocol
Method	GET
URI	/protocol/{id}
Parameters	none
Header Parameters	subjectid:SECURITY-TOKEN
Media Type (input)	none
Results	The metadata representation in supported media type
Media Type (output)	text/uri-list;application/rdf+xml;text/n3
Status code	200,400,401,402,403

Links: Page, Edit with form

Retrieve Protocol files

Description	Retrieves the document, describing the protocol
Resource	Protocol
Method	GET
URI	/protocol/{id}/document
Parameters	none
Header Parameters	subjectid:SECURITY-TOKEN
Media Type (input)	none
Results	Protocol content in one of supported MIME format
Media Type (output)	application/pdf;application/msword
Status code	200,400,401,402,403

Links: Page, Edit with form

cURL example - retrieve the protocol in PDF and Word formats

curl -X GET -H "application/pdf"  /protocol/id/file -H "subjectid:TOKEN"

curl -X GET -H "application/msword"  /protocol/id/file -H "subjectid:TOKEN"

Protocol versions

N3 representation of a Protocol with a previous version

<http://toxbank.net/services/protocol/Protocol_10>    a       tb:Protocol ;
     tb:hasAbstract "New abstract"^^xsd:string ;
     tb:isSummarySearchable
             "false"^^xsd:boolean ;
     tb:protocolPriorVersion
             <http://toxbank.net/services/protocol/Protocol_9> ;
     tb:submissionDate
             "2011-09-15T00:00:00"^^xsd:dateTime ;
     tb:versionInfo "2011-09-15"^^xsd:string .

Retrieve versions of a single Protocol

Description	Retrieves the protocol versions
Resource	Protocol
Method	GET
URI	/protocol/{id}/versions
Parameters	none, or ?search=name or paging parameters: page, pagesize
Header Parameters	subjectid:SECURITY-TOKEN
Media Type (input)	none
Results	The protocol URI or other supported representation
Media Type (output)	text/uri-list;application/rdf+xml;text/n3
Status code	200,400,401,402,403

Links: Page, Edit with form

Upload a new Protocol version

Description	Uploads a newprotocol version
Resource	Protocol
Method	POST
URI	/protocol/{id}/versions
Parameters	(see cURL example)
Header Parameters	subjectid:SECURITY-TOKEN
Media Type (input)	multipart/form-data
Results	Task representation in supported MIME formats
Media Type (output)	text/uri-list;application/rdf+xml;text/n3
Status code	200,202,400,401,402,403

Links: Page, Edit with form

Security

Only a Principal Investigator (PI) is allowed to upload protocols

Design

• Be able to specify if the user is a PI - upon registration, or later.
• Create OpenSSO group for PI, and a policy, allowing member of the PI group to POST to /protocols
• On protocol upload, create write/update policy, allowing only the submitter to modify /protocol/id

Protocol read rights are specified on upload, and can be modified later by the PI

Design

• Access levels, entered via GUI have to be translated into an OpenSSO policy.

            -Only authors  - create specific policy for set of user names
            -Consortium - create policy for the group, corresponding to the selected project(s)
            -SEURAT -  create policy for the group, corresponding to the entire SEURAT cluster
            -Public -   create policy for the a group, corresponding to all registered users
            -Custom access - create specific policy for a set of user names

RDF representation

RDF N3

This RDF representation is automatically generated by the latest version of the Toxbank Java client library