Protocol

From ToxBank API Wiki
(Redirected from API Protocol)
Jump to: navigation, search
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