Protocol

From ToxBank API Wiki
(Difference between revisions)
Jump to: navigation, search
m (cURL example)
(cURL example: added more examples)
Line 40: Line 40:
 
=== PUT: Update Protocol metadata ===
 
=== PUT: Update Protocol metadata ===
 
{{HasOperation |id=API_Protocol:Update}}
 
{{HasOperation |id=API_Protocol:Update}}
==== cURL example ====
+
==== cURL example - update protocol metadata ====
  curl -X PUT -H 'subjectid:TOKEN' -H 'Content-Type:application/x-www-form-urlencoded' \
+
  curl -X PUT -H 'subjectid:TOKEN' -H 'Content-Type:multipart/form-data' \
  -d 'title=VALUE' -d 'anabstract=VALUE' -d 'author_uri=VALUE' \
+
  -F 'title=VALUE' -F 'anabstract=VALUE' -F 'author_uri=VALUE' \
  -d 'keywords=VALUE' -d 'summarySearchable=VALUE' http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-1-1
+
  -F 'keywords=VALUE' -F 'summarySearchable=VALUE' http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-1-1
 +
 
 +
==== cURL example - Update metadata, protocol file and the published flag ====
 +
curl -X PUT -H 'subjectid:TOKEN' -H 'Content-Type:multipart/form-data' \
 +
-F 'title=VALUE' -F 'anabstract=VALUE' -d 'published=true' \
 +
-F "file=@updated.pdf" http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-1-1
 +
 
 +
==== cURL example - Update the published flag only ====
 +
$ curl -X PUT -H "subjectid:TOKEN" -H "Content-Type:multipart/form-data" \
 +
-F "published=true" http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-269-25 -iv
  
 
== Documents ==
 
== Documents ==

Revision as of 17:01, 11 April 2012

Protocol


A Protocol contains a single MSWord or PDF document, describing how to perform certain experiment (lab or in-silico), and metadata. A Protocol defines a Data template. The results of performing the experiment are recorded in a (set of) Investigations. A Protocol may have versions. A Protocol version is another Protocol.

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

Contents

REST interface

Protocol

GET: 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
curl -X GET -H 'Accept:text/uri-list' -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/protocol?modifiedSince=1293837000000

GET: 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


Example: http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-1-1

cURL example

curl -X GET -H 'Accept:application/rdf+xml' -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-1-1

POST: 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


cURL example

curl -X POST -H 'subjectid:TOKEN' -H 'Content-Type:multipart/form-data' -F 'filename=@FILE_NAME' \
-d 'title=VALUE' -d 'anabstract=VALUE' -d 'author_uri=VALUE' -d 'author_uri=VALUE' -d 'author_uri=VALUE' \
-d 'keywords=VALUE' -d 'summarySearchable=VALUE' -d 'project_uri=Project URI' -d 'organisation_uri=Organisation URI' 
-d 'user_uri=Owner User URI' http://toxbanktest1.opentox.org:8080/toxbank/protocol

PUT: Update Protocol metadata

Description Updates a protocol
Resource Protocol
Method PUT
URI /protocol/{id}
Parameters (see cURL example)
Header Parameters subjectid:SECURITY-TOKEN
Media Type (input) application/x-www-form-urlencoded
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


cURL example - update protocol metadata

curl -X PUT -H 'subjectid:TOKEN' -H 'Content-Type:multipart/form-data' \
-F 'title=VALUE' -F 'anabstract=VALUE' -F 'author_uri=VALUE' \
-F 'keywords=VALUE' -F 'summarySearchable=VALUE' http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-1-1

cURL example - Update metadata, protocol file and the published flag

curl -X PUT -H 'subjectid:TOKEN' -H 'Content-Type:multipart/form-data' \
-F 'title=VALUE' -F 'anabstract=VALUE' -d 'published=true' \
-F "file=@updated.pdf" http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-1-1

cURL example - Update the published flag only

$ curl -X PUT -H "subjectid:TOKEN" -H "Content-Type:multipart/form-data" \
-F "published=true" http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-269-25 -iv

Documents

GET: Retrieve the protocol file

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


Example http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-30-3/document

cURL example

 curl -X GET -H 'Accept:application/pdf' -H 'subjectid:TOKEN' \
                    http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-30-3/document
 curl -X GET -H 'Accept:application/msword' -H 'subjectid:TOKEN' \
                    http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-30-3/document

POST: Upload the protocol file

Once uploaded via [1], a protocol file can't be modified. However, a new version of the protocol could be uploaded.

Versions

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

GET: 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


cURL example

curl -X GET -H 'Accept:SUPPORTED-MEDIA-TYPE' -H 'subjectid:TOKEN' \
               http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-30-4/versions

POST: 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


cURL example

curl -X POST -H 'subjectid:TOKEN' -H 'Content-Type:application/x-www-form-urlencoded' -F 'filename=@FILE_NAME' \
             -d 'title=VALUE' -d 'anabstract=VALUE' -d 'author_uri=VALUE' -d 'author_uri=VALUE'  \
             -d 'keywords=VALUE' -d 'summarySearchable=VALUE' -d 'project_uri=Project URI' \
             -d 'organisation_uri=Organisation URI' -d 'user_uri=Owner User URI' \
             http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-30-4/versions

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

Protocol.full.n3

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

Personal tools