Protocol
(→N3 representation of a Protocol) |
m (→PUT: Update Protocol metadata) |
||
(68 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
− | {{REST_resource | + | {{REST_resource}} |
− | }} | + | |
− | [[API_Protocol| | + | 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 | + | 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 | + | 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 | ||
− | === | + | = REST interface = |
+ | == Protocol == | ||
− | ==== | + | === GET: Retrieve the list of Protocols === |
+ | {{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 |
− | = | + | 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}} | |
− | + | 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 -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 === |
− | + | {{HasOperation |id=API_Protocol:Upload}} | |
− | + | ==== 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 === | |
− | + | {{HasOperation |id=API_Protocol:Update}} | |
+ | ==== 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 - | + | ==== 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}} | ||
+ | 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 -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 | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | == Retrieve versions of a single Protocol == | + | === 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. | ||
+ | |||
+ | == Versions == | ||
+ | A Protocol may have versions. A Protocol version is another 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' \ | ||
+ | http://toxbanktest1.opentox.org:8080/toxbank/protocol/SEURAT-Protocol-30-4/versions | ||
− | == 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 = | ||
+ | |||
+ | ==== 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 | ||
+ | [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]] | ||
+ | |||
+ | |||
+ | 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: | ||
+ | |||
+ | *'''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 = | ||
+ | |||
+ | == 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] | ||
+ | |||
+ | == 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
 | ||
+ | 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> | ||
+ | |||
+ | |||
+ | </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:
- allowReadByUser : An URI of an existing ToxBank user, e.g. http://toxbanktest1.opentox.org:8080/toxbank/user/U1
- allowReadByGroup : An URI of existing ToxBank consortium or organisation.
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
- Generates XML policy, (without sending), part of the Java OpenTox AA client. The OpenTox AA client supports login in and sending / retrieving the policies.
- Java beans for access rights and policy rules;
- Java Client, convenience methods for communication with the policy service. The real work is done by the Java OpenTox AA client.
RDF representation
Stable version
This RDF representation is automatically generated by the production version of the Toxbank Java client library
Alpha test version
This RDF representation is automatically generated by the alpha test version of the Toxbank Java client library
Development version
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>