Protocol

From ToxBank API Wiki
(Difference between revisions)
Jump to: navigation, search
m
m (PUT: Update Protocol metadata)
 
(39 intermediate revisions by one user not shown)
Line 1: Line 1:
 
{{REST_resource}}
 
{{REST_resource}}
  
[[API_Protocol|Protocols]] contain a single MSWord or PDF document, describing how to perform certain experiment (lab or in-silico), and metadata. A Protocol defines a [[API_Protocol:RetrieveTemplate|Data template]].  
+
A [[API_Protocol|Protocol]] contains a single MSWord or PDF document, describing how to perform certain experiment (lab or in-silico), and metadata. 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]].  
 
A [[API_Protocol|Protocol]] may have [[API_Protocol#Protocol_versions_REST_interface|versions]]. A Protocol version is another [[API_Protocol|Protocol]].  
 
A [[API_Protocol|Protocol]] may have [[API_Protocol#Protocol_versions_REST_interface|versions]]. A Protocol version is another [[API_Protocol|Protocol]].  
Line 9: Line 9:
 
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
  
= Protocol metadata REST interface =
+
= REST interface =
 +
== Protocol ==
  
== GET: Retrieve the list of Protocols ==
+
=== GET: 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]
 
Example: [http://toxbanktest1.opentox.org:8080/toxbank/protocol http://toxbanktest1.opentox.org:8080/toxbank/protocol]
=== cURL example ===
+
==== 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:text/uri-list' -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/protocol  
  
Line 21: Line 22:
 
  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?page=0&pagesize=5
  
== GET: Retrieve Metadata of a single Protocol ==
+
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 ===
 
{{HasOperation |id=API_Protocol:RetrieveMetadata}}
 
{{HasOperation |id=API_Protocol:RetrieveMetadata}}
 
Example: [http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-1-1  http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-1-1]
 
Example: [http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-1-1  http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-1-1]
=== cURL example ===
+
==== cURL example ====
 
  curl -X GET -H 'Accept:application/rdf+xml' -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-1-1
 
  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 ==
+
=== POST: Upload a new Protocol ===
 
{{HasOperation |id=API_Protocol:Upload}}
 
{{HasOperation |id=API_Protocol:Upload}}
=== cURL example ===
+
==== cURL example ====
 
  curl -X POST -H 'subjectid:TOKEN' -H 'Content-Type:multipart/form-data' -F 'filename=@FILE_NAME' \
 
  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 'title=VALUE' -d 'anabstract=VALUE' -d 'author_uri=VALUE' -d 'author_uri=VALUE' -d 'author_uri=VALUE' \
Line 35: Line 38:
 
  -d 'user_uri=Owner User URI' http://toxbanktest1.opentox.org:8080/toxbank/protocol
 
  -d 'user_uri=Owner User URI' http://toxbanktest1.opentox.org:8080/toxbank/protocol
  
== 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
  
= Protocol documents REST interface =
+
==== cURL example - Update metadata, protocol file and the published flag ====
== GET: Retrieve the protocol file ==
+
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
 +
 
 +
Note all update (PUT) and create (POST) examples use multipart/form-data, regardless of whether file is uploaded or not.
 +
 
 +
The published flag is part of the RDF representation
 +
 
 +
http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-269-25 -H "Accept:text/n3"
 +
@prefix tb:      <http://onto.toxbank.net/api/> .
 +
[output skipped]
 +
tbpl:SEURAT-Protocol-269-25
 +
      a      tb:Protocol ;
 +
        tb:isPublished "true"^^xsd:boolean ;
 +
  [output skipped]
 +
 
 +
=== POST: Publish a protocol ===
 +
 
 +
To change only the publish flag, use POST to /protocol/{id}/publication resource
 +
 
 +
==== cURL example - Update metadata, protocol file and the published flag ====
 +
curl -X POST -H 'subjectid:TOKEN' -H 'Content-Type:multipart/form-data' \
 +
-d 'published=true'  http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-1-1/publication
 +
 
 +
== Documents ==
 +
=== GET: Retrieve the protocol file ===
 
{{HasOperation |id=API_Protocol:Retrieve}}
 
{{HasOperation |id=API_Protocol:Retrieve}}
 
Example [http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-30-3/document?media=application%2Fpdf http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-30-3/document]
 
Example [http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-30-3/document?media=application%2Fpdf http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-30-3/document]
=== cURL example ===
+
==== cURL example ====
  
 
   curl -X GET -H 'Accept:application/pdf' -H 'subjectid:TOKEN' \
 
   curl -X GET -H 'Accept:application/pdf' -H 'subjectid:TOKEN' \
Line 54: Line 86:
 
                     http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-30-3/document
 
                     http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-30-3/document
  
== POST: Upload the protocol file ==
+
=== POST: Upload the protocol file ===
 
    
 
    
 
Once uploaded via [http://api.toxbank.net/index.php/Protocol#POST:_Upload_a_new_Protocol], a protocol file can't be modified. However, a new version of the protocol could be uploaded.
 
Once uploaded via [http://api.toxbank.net/index.php/Protocol#POST:_Upload_a_new_Protocol], a protocol file can't be modified. However, a new version of the protocol could be uploaded.
  
= Protocol versions REST interface =
+
== Versions ==
 
+
A Protocol may have versions. A Protocol version is another Protocol.
=== cURL example ===
+
=== GET: Retrieve versions of a single Protocol ===
== GET: Retrieve versions of a single Protocol ==
+
 
{{HasOperation |id=API_Protocol:RetrieveVersions }}
 
{{HasOperation |id=API_Protocol:RetrieveVersions }}
 +
==== cURL example ====
 
  curl -X GET -H 'Accept:SUPPORTED-MEDIA-TYPE' -H 'subjectid:TOKEN' \
 
  curl -X GET -H 'Accept:SUPPORTED-MEDIA-TYPE' -H 'subjectid:TOKEN' \
 
                 http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-30-4/versions
 
                 http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-30-4/versions
  
== POST: Upload a new Protocol version ==
+
=== POST: Upload a new Protocol version ===
 
{{HasOperation |id=API_Protocol:UploadVersion}}
 
{{HasOperation |id=API_Protocol:UploadVersion}}
 
+
====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 'keywords=VALUE' -d 'summarySearchable=VALUE' -d 'project_uri=Project URI' \
 +
              -d 'organisation_uri=Organisation URI' -d 'user_uri=Owner User URI' \
 +
              -d 'allowReadByUser=User URI' \
 +
              http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-30-4/versions
  
 
= Security =
 
= Security =
  
==== Only a Principal Investigator (PI) is allowed to upload protocols  ====
+
==== SEURAT-1 access ====
  
=====Design=====
+
All SEURAT-1 members are allowed to upload protocols.  
*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 
+
This is ensured by allowing POST and GET to http://services.toxbank.net/toxbank/protocol to the members of groups coach,scrtox,hemibio,notox,cosmos,toxbank,detective,sep.
*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 ====
+
The policies can be browsed
 +
[https://services.toxbank.net/toxbank/admin/policy?search=https%3A%2F%2Fservices.toxbank.net%2Ftoxbank%2Fprotocol here].
 +
A XACML policy template [[File:Policy-allconsortia.xml]]
  
=====Design=====
+
*Access levels, entered via GUI have to be translated into an OpenSSO policy.
+
Note: During the alpha test only a Principal Investigator (PI) is allowed to upload protocols.
 +
This was ensured by allowing POST and GET to http://toxbanktest1.opentox.org:8080/toxbank/protocol to the LDAP '''PI''' group members only. This is now changed!
  
            -Only authors  - create specific policy for set of user names
+
==== Protocol read rights are specified on upload, and can be modified later by the protocol owner ====
            -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
+
  
 +
Access levels, entered via GUI are translated into an OpenSSO policy by the protocol service. The following fields are added to the multipart web form, sent on PUT or POST. There could be more than one field of each type:
 +
 +
*'''allowReadByUser''' : An URI of an existing ToxBank user, e.g. http://toxbanktest1.opentox.org:8080/toxbank/user/U1
 +
*'''allowReadByGroup''' : An URI of existing ToxBank [http://toxbanktest1.opentox.org:8080/toxbank/project/G1 consortium] or [http://toxbanktest1.opentox.org:8080/toxbank/organisation/G1 organisation].
 +
 +
The protocol service reads the multipart web form, generates OpenAM [http://en.wikipedia.org/wiki/XACML XACML] policy and sends it to the [http://opensso.in-silico.ch/opensso/policy OpenTox policy service], upon successful POST or PUT operation. The old policy for the same URI is deleted.
 +
 +
The UI generates the web form fields as follows:
 +
 +
*Only authors  - Fills '''allowReadByUser''' fields with the authors URIs. The users are associated with the corresponding LDAP user names via [http://toxbanktest1.opentox.org:8080/toxbank/user/U1?media=text%2Fn3 tb:hasAccount]
 +
*Consortium - Fills '''allowReadByGroup''' fields with the project URIs. The projects are associated with the corresponding LDAP groups via [http://toxbanktest1.opentox.org:8080/toxbank/project/G2?media=text%2Fn3 tb:hasAccount]
 +
*SEURAT -  Fills '''allowReadByGroup''' fields with all project URIs, which are defined as [http://toxbanktest1.opentox.org:8080/toxbank/project?media=text%2Fn3 tb:subOrganisationOf SEURAT-1]
 +
*Public -  Fills '''allowReadByGroup''' field with the URI of a [http://toxbanktest1.opentox.org:8080/toxbank/organisation/G176 "Public" organisation]. The public organisation is associated to the LDAP group "'''member'''"
 +
*Custom access - Fills '''allowReadByUser''' fields with selected user URIs
 +
 +
=====Only the protocol owner can update the protocol =====
 +
 +
The protocol service adds to the policy a rule, allowing full access for the protocol owner.
 +
 +
 +
==== cURL example - Update the access rights  only ====
 +
$ curl -X PUT -H "subjectid:TOKEN" -H "Content-Type:multipart/form-data" \
 +
--form "allowReadByUser=http://toxbanktest1.opentox.org:8080/toxbank/user/U1" http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-269-25 -iv
 +
 +
Note all update (PUT) and create (POST) examples use multipart/form-data, regardless of whether file is uploaded or not.
 +
 +
=====Implementation =====
 +
*[https://github.com/vedina/opentox-aa-cli/blob/master/src/main/java/org/opentox/aa/policy/PolicyParser.java Generates XML policy, (without sending)], part of the [http://vedina.github.com/opentox-aa-cli/ Java OpenTox AA client]. The OpenTox AA client supports login in and sending / retrieving the policies.
 +
*[https://github.com/ToxBank/toxbank-api-beans/tree/master/src/main/java/net/toxbank/client/policy Java beans] for access rights and policy rules;
 +
*[https://github.com/ToxBank/toxbank-api-client/blob/master/src/main/java/net/toxbank/client/TBClient.java Java Client], convenience methods for communication with the policy service. The real work is done by the [http://vedina.github.com/opentox-aa-cli/ Java OpenTox AA client].
  
 
= RDF representation =
 
= RDF representation =
+
 
[http://jenkins.toxbank.net/job/toxbank-api-beans/net.toxbank$toxbank-api-beans/ws/target/test-classes/ RDF N3]
+
== Stable version ==
 +
[http://jenkins.toxbank.net/job/production-toxbank-api-beans/ws/target/test-classes/Protocol.full.n3]
 +
 
 +
This RDF representation is automatically generated by the production version of the [https://github.com/ToxBank/toxbank-api-beans/tree/toxbank-api-beans-0.0.2 Toxbank Java client library]
 +
 
 +
== Alpha test version ==
 +
[http://jenkins.toxbank.net/job/alpha-toxbank-api-beans/ws/target/test-classes/Protocol.full.n3]
 +
 
 +
This RDF representation is automatically generated by the alpha test version of the [https://github.com/ToxBank/toxbank-api-beans/tree/alphatest Toxbank Java client library]
 +
 
 +
== Development version ==
 +
[http://jenkins.toxbank.net/job/dev-toxbank-api-beans/ws/target/test-classes/Protocol.full.n3]
  
 
This RDF representation is automatically generated by the latest version of the [https://github.com/ToxBank/toxbank-api-beans Toxbank Java client library]
 
This RDF representation is automatically generated by the latest version of the [https://github.com/ToxBank/toxbank-api-beans Toxbank Java client library]
 +
 +
== Example in RDF/XML  ==
 +
 +
<pre>
 +
 +
<?xml version="1.0"?>
 +
<!DOCTYPE rdf:RDF [
 +
  <!ENTITY tb 'http://onto.toxbank.net/api/'>
 +
  <!ENTITY foaf 'http://xmlns.com/foaf/0.1/'>
 +
  <!ENTITY tbpl 'http://toxbanktest1.opentox.org:8080/toxbank/protocol/'>
 +
  <!ENTITY SEURAT-Protocol-3-1 'http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-3-1/'>
 +
  <!ENTITY tbo 'http://toxbanktest1.opentox.org:8080/toxbank/organisation/'>
 +
  <!ENTITY xsd 'http://www.w3.org/2001/XMLSchema#'>
 +
  <!ENTITY rdf 'http://www.w3.org/1999/02/22-rdf-syntax-ns#'>
 +
  <!ENTITY tbpt 'http://toxbanktest1.opentox.org:8080/toxbank/project/'>
 +
  <!ENTITY tbu 'http://toxbanktest1.opentox.org:8080/toxbank/user/'>
 +
  <!ENTITY dcterms 'http://purl.org/dc/terms/'>]>
 +
<rdf:RDF
 +
    xmlns:SEURAT-Protocol-3-1="&SEURAT-Protocol-3-1;"
 +
    xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
 +
    xmlns:foaf="&foaf;"
 +
    xmlns:tbo="&tbo;"
 +
    xmlns:tbu="&tbu;"
 +
    xmlns:dcterms="&dcterms;"
 +
    xmlns:xsd="&xsd;"
 +
    xmlns:tbpt="&tbpt;"
 +
    xmlns:tbpl="&tbpl;"
 +
    xmlns:tb="&tb;">
 +
  <tb:Protocol rdf:about="&tbpl;SEURAT-Protocol-3-1">
 +
    <tb:isSummarySearchable rdf:datatype="&xsd;boolean">true</tb:isSummarySearchable>
 +
    <tb:hasProject>
 +
      <tb:Project rdf:about="&tbpt;G2">
 +
        <tb:subOrganisationOf rdf:resource="SEURAT-1"/>
 +
        <tb:hasAccount rdf:datatype="&xsd;string">toxbank</tb:hasAccount>
 +
        <dcterms:title rdf:datatype="&xsd;string">ToxBank</dcterms:title>
 +
      </tb:Project>
 +
    </tb:hasProject>
 +
    <tb:hasKeyword rdf:datatype="&xsd;string">http://www.owl-ontologies.com/toxbank.owl/K347</tb:hasKeyword>
 +
    <tb:hasKeyword rdf:datatype="&xsd;string">http://www.owl-ontologies.com/toxbank.owl/K258</tb:hasKeyword>
 +
    <dcterms:dateSubmitted rdf:datatype="&xsd;long">1338406901000</dcterms:dateSubmitted>
 +
    <dcterms:title rdf:datatype="&xsd;string">TDx/TDxFLx Acetaminophen assay</dcterms:title>
 +
    <tb:hasOwner rdf:resource="&tbu;U115"/>
 +
    <tb:hasVersionInfo rdf:datatype="&xsd;long">1</tb:hasVersionInfo>
 +
    <tb:hasAuthor>
 +
      <foaf:Person rdf:about="&tbu;U184">
 +
        <foaf:holdsAccount>
 +
          <foaf:OnlineAccount rdf:about="mailto:null">
 +
            <foaf:accountServiceHomepage rdf:datatype="&xsd;string"
 +
            >mailto</foaf:accountServiceHomepage>
 +
          </foaf:OnlineAccount>
 +
        </foaf:holdsAccount>
 +
        <foaf:family_name rdf:datatype="&xsd;string">Peterson</foaf:family_name>
 +
        <foaf:givenname rdf:datatype="&xsd;string">C.</foaf:givenname>
 +
      </foaf:Person>
 +
    </tb:hasAuthor>
 +
    <dcterms:identifier rdf:datatype="&xsd;string">SEURAT-Protocol-3-1</dcterms:identifier>
 +
    <tb:hasAbstract rdf:datatype="&xsd;string">The TDx/TDxFLx Acetaminophen assay is a reagent system for the&#xD;
 +
quantitative measurement of acetaminophen in human serum or plasma.&#xD;
 +
Measurements obtained are used in the diagnosis and treatment of&#xD;
 +
acetaminophen overdose.</tb:hasAbstract>
 +
    <tb:hasDocument rdf:resource="&SEURAT-Protocol-3-1;document"/>
 +
    <tb:isPublished rdf:datatype="&xsd;boolean">true</tb:isPublished>
 +
    <tb:hasOrganisation>
 +
      <tb:Organization rdf:about="&tbo;G274">
 +
        <dcterms:title rdf:datatype="&xsd;string">Abbott</dcterms:title>
 +
      </tb:Organization>
 +
    </tb:hasOrganisation>
 +
    <tb:hasStatus rdf:datatype="&xsd;string">SOP</tb:hasStatus>
 +
    <dcterms:modified rdf:datatype="&xsd;long">1338475897000</dcterms:modified>
 +
  </tb:Protocol>
 +
</rdf:RDF>
 +
 +
 +
</pre>

Latest revision as of 04:26, 18 July 2014

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

Note all update (PUT) and create (POST) examples use multipart/form-data, regardless of whether file is uploaded or not.

The published flag is part of the RDF representation

http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-269-25 -H "Accept:text/n3"
@prefix tb:      <http://onto.toxbank.net/api/> .
[output skipped] 
tbpl:SEURAT-Protocol-269-25
     a       tb:Protocol ;
       tb:isPublished "true"^^xsd:boolean ;
 [output skipped]

POST: Publish a protocol

To change only the publish flag, use POST to /protocol/{id}/publication resource 

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

curl -X POST -H 'subjectid:TOKEN' -H 'Content-Type:multipart/form-data' \
-d 'published=true'  http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-1-1/publication

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:multipart/form-data' -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' \
             -d 'allowReadByUser=User URI' \
             http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-30-4/versions

Security

SEURAT-1 access

All SEURAT-1 members are allowed to upload protocols.

This is ensured by allowing POST and GET to http://services.toxbank.net/toxbank/protocol to the members of groups coach,scrtox,hemibio,notox,cosmos,toxbank,detective,sep.

The policies can be browsed here. A XACML policy template File:Policy-allconsortia.xml


Note: During the alpha test only a Principal Investigator (PI) is allowed to upload protocols. This was ensured by allowing POST and GET to http://toxbanktest1.opentox.org:8080/toxbank/protocol to the LDAP PI group members only. This is now changed!

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

Access levels, entered via GUI are translated into an OpenSSO policy by the protocol service. The following fields are added to the multipart web form, sent on PUT or POST. There could be more than one field of each type:

The protocol service reads the multipart web form, generates OpenAM XACML policy and sends it to the OpenTox policy service, upon successful POST or PUT operation. The old policy for the same URI is deleted.

The UI generates the web form fields as follows:

  • Only authors - Fills allowReadByUser fields with the authors URIs. The users are associated with the corresponding LDAP user names via tb:hasAccount
  • Consortium - Fills allowReadByGroup fields with the project URIs. The projects are associated with the corresponding LDAP groups via tb:hasAccount
  • SEURAT - Fills allowReadByGroup fields with all project URIs, which are defined as tb:subOrganisationOf SEURAT-1
  • Public - Fills allowReadByGroup field with the URI of a "Public" organisation. The public organisation is associated to the LDAP group "member"
  • Custom access - Fills allowReadByUser fields with selected user URIs
Only the protocol owner can update the protocol

The protocol service adds to the policy a rule, allowing full access for the protocol owner.


cURL example - Update the access rights only

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

Note all update (PUT) and create (POST) examples use multipart/form-data, regardless of whether file is uploaded or not.

Implementation

RDF representation

Stable version

[2]

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

Alpha test version

[3]

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

Development version

[4]

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

Example in RDF/XML


<?xml version="1.0"?>
<!DOCTYPE rdf:RDF [
  <!ENTITY tb 'http://onto.toxbank.net/api/'>
  <!ENTITY foaf 'http://xmlns.com/foaf/0.1/'>
  <!ENTITY tbpl 'http://toxbanktest1.opentox.org:8080/toxbank/protocol/'>
  <!ENTITY SEURAT-Protocol-3-1 'http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-3-1/'>
  <!ENTITY tbo 'http://toxbanktest1.opentox.org:8080/toxbank/organisation/'>
  <!ENTITY xsd 'http://www.w3.org/2001/XMLSchema#'>
  <!ENTITY rdf 'http://www.w3.org/1999/02/22-rdf-syntax-ns#'>
  <!ENTITY tbpt 'http://toxbanktest1.opentox.org:8080/toxbank/project/'>
  <!ENTITY tbu 'http://toxbanktest1.opentox.org:8080/toxbank/user/'>
  <!ENTITY dcterms 'http://purl.org/dc/terms/'>]>
<rdf:RDF
    xmlns:SEURAT-Protocol-3-1="&SEURAT-Protocol-3-1;"
    xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:foaf="&foaf;"
    xmlns:tbo="&tbo;"
    xmlns:tbu="&tbu;"
    xmlns:dcterms="&dcterms;"
    xmlns:xsd="&xsd;"
    xmlns:tbpt="&tbpt;"
    xmlns:tbpl="&tbpl;"
    xmlns:tb="&tb;">
  <tb:Protocol rdf:about="&tbpl;SEURAT-Protocol-3-1">
    <tb:isSummarySearchable rdf:datatype="&xsd;boolean">true</tb:isSummarySearchable>
    <tb:hasProject>
      <tb:Project rdf:about="&tbpt;G2">
        <tb:subOrganisationOf rdf:resource="SEURAT-1"/>
        <tb:hasAccount rdf:datatype="&xsd;string">toxbank</tb:hasAccount>
        <dcterms:title rdf:datatype="&xsd;string">ToxBank</dcterms:title>
      </tb:Project>
    </tb:hasProject>
    <tb:hasKeyword rdf:datatype="&xsd;string">http://www.owl-ontologies.com/toxbank.owl/K347</tb:hasKeyword>
    <tb:hasKeyword rdf:datatype="&xsd;string">http://www.owl-ontologies.com/toxbank.owl/K258</tb:hasKeyword>
    <dcterms:dateSubmitted rdf:datatype="&xsd;long">1338406901000</dcterms:dateSubmitted>
    <dcterms:title rdf:datatype="&xsd;string">TDx/TDxFLx Acetaminophen assay</dcterms:title>
    <tb:hasOwner rdf:resource="&tbu;U115"/>
    <tb:hasVersionInfo rdf:datatype="&xsd;long">1</tb:hasVersionInfo>
    <tb:hasAuthor>
      <foaf:Person rdf:about="&tbu;U184">
        <foaf:holdsAccount>
          <foaf:OnlineAccount rdf:about="mailto:null">
            <foaf:accountServiceHomepage rdf:datatype="&xsd;string"
            >mailto</foaf:accountServiceHomepage>
          </foaf:OnlineAccount>
        </foaf:holdsAccount>
        <foaf:family_name rdf:datatype="&xsd;string">Peterson</foaf:family_name>
        <foaf:givenname rdf:datatype="&xsd;string">C.</foaf:givenname>
      </foaf:Person>
    </tb:hasAuthor>
    <dcterms:identifier rdf:datatype="&xsd;string">SEURAT-Protocol-3-1</dcterms:identifier>
    <tb:hasAbstract rdf:datatype="&xsd;string">The TDx/TDxFLx Acetaminophen assay is a reagent system for the
quantitative measurement of acetaminophen in human serum or plasma.
Measurements obtained are used in the diagnosis and treatment of
acetaminophen overdose.</tb:hasAbstract>
    <tb:hasDocument rdf:resource="&SEURAT-Protocol-3-1;document"/>
    <tb:isPublished rdf:datatype="&xsd;boolean">true</tb:isPublished>
    <tb:hasOrganisation>
      <tb:Organization rdf:about="&tbo;G274">
        <dcterms:title rdf:datatype="&xsd;string">Abbott</dcterms:title>
      </tb:Organization>
    </tb:hasOrganisation>
    <tb:hasStatus rdf:datatype="&xsd;string">SOP</tb:hasStatus>
    <dcterms:modified rdf:datatype="&xsd;long">1338475897000</dcterms:modified>
  </tb:Protocol>
</rdf:RDF>


Personal tools