Protocol

From ToxBank API Wiki
(Difference between revisions)
Jump to: navigation, search
m
m
Line 1: Line 1:
 
{{REST_resource}}
 
{{REST_resource}}
  
 +
= Content =
 +
 +
== Document ==
 
[[API_Protocol|Protocols]] contain a single MSWord or PDF document, describing how to perform certain experiment (lab or in-silico), and metadata.
 
[[API_Protocol|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 [[API_Protocol:RetrieveTemplate|Data template]].
 
The results of performing the experiment are recorded in a (set of) [[Investigation|Investigations]].  
 
The results of performing the experiment are recorded in a (set of) [[Investigation|Investigations]].  
  
 +
== Versions ==
 
A [[API_Protocol|Protocol]] may have [[API_Protocol#Protocol_versions|versions]]. A Protocol version is another [[API_Protocol|Protocol]].  
 
A [[API_Protocol|Protocol]] may have [[API_Protocol#Protocol_versions|versions]]. A Protocol version is another [[API_Protocol|Protocol]].  
  
−
A Protocol includes links to a [[API_Protocol:RetrieveTemplate|Data template]] URI , its [[API_User|Author(s)]],
+
== Authors, Owners, Organisations, Project ==
−
related [[API_Project|Project)]] and [[API_Organisation|Organisation)]]. The protocol [[API_User|Owner]] is assigned automatically, when the protocol is uploaded by a logged-in user.  
+
A Protocol includes links to [[API_User|Author(s)]], related [[Project]] and [[Organisation]]. The protocol [[API_User|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
 
TBD: Parameter names to be added to the protocol representation, as in ISA-TAB
  
−
=== Security ===
+
= Security =
  
 
==== Only a Principal Investigator (PI) is allowed to upload protocols  ====
 
==== Only a Principal Investigator (PI) is allowed to upload protocols  ====
Line 34: Line 41:
 
   
 
   
 
[http://jenkins.toxbank.net/job/toxbank-api-beans/net.toxbank$toxbank-api-beans/ws/target/test-classes/ N3 examples], generated by [https://github.com/ToxBank/toxbank-api-beans toxbank-api-beans] code.
 
[http://jenkins.toxbank.net/job/toxbank-api-beans/net.toxbank$toxbank-api-beans/ws/target/test-classes/ N3 examples], generated by [https://github.com/ToxBank/toxbank-api-beans toxbank-api-beans] code.
 +
 +
= REST interface =
  
 
== Retrieve the List of Protocols ==
 
== Retrieve the List of Protocols ==

Revision as of 13:14, 14 December 2011

Protocol


Contents

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

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

N3 representation of a Protocol

N3 examples, generated by toxbank-api-beans code.

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



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


Retrieved from "http://api.toxbank.net/index.php/Protocol"
Facts about ProtocolRDF feed
HasOperationAPI Protocol:RetrieveList  +, API Protocol:Upload  +, API Protocol:RetrieveMetadata  +, API Protocol:Retrieve  +, API Protocol:RetrieveVersions  + and API Protocol:UploadVersion  +
Personal tools