User
m (Added summary) |
(→cURL example) |
||
(24 intermediate revisions by one user not shown) | |||
Line 10: | Line 10: | ||
= REST interface = | = REST interface = | ||
− | == Retrieve users == | + | == GET: Retrieve users == |
{{HasOperation |id=User:RetrieveList}} | {{HasOperation |id=User:RetrieveList}} | ||
− | + | Example: [http://toxbanktest1.opentox.org:8080/toxbank/user http://toxbanktest1.opentox.org:8080/toxbank/user] | |
=== cURL example === | === cURL example === | ||
− | curl -X GET /user | + | curl -X GET -H 'Accept:text/uri-list' -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/user |
− | + | curl -X GET -H 'Accept:application/rdf+xml' -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/user?search=J | |
+ | curl -X GET -H 'Accept:application/rdf+xml' -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/user?username=guest | ||
+ | |||
+ | curl -X GET -H 'Accept:text/uri-list' -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/user?page=0&pagesize=5 | ||
+ | |||
+ | == GET: Retrieve user details == | ||
{{HasOperation |id=User:Details}} | {{HasOperation |id=User:Details}} | ||
+ | === cURL example === | ||
+ | curl -X GET -H 'Accept:application/rdf+xml' -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/user/U1 | ||
− | == | + | ==POST: Create an User == |
+ | {{REST Operations | ||
+ | |REST_op_description=Creates an user | ||
+ | |REST_resource=User | ||
+ | |REST_op_method=POST | ||
+ | |REST_op_uri=/user | ||
+ | |REST_op_params=(see the cURL example) | ||
+ | |REST_header_param=subjectid:SECURITY-TOKEN | ||
+ | |REST_op_mime_input=application/x-www-form-urlencoded | ||
+ | |REST_op_result=Task representation in supported MIME formats | ||
+ | |REST_op_mime_output=application/rdf+xml;text/n3;text/uri-list | ||
+ | |REST_op_status=200,202,400,401,402,403,500 | ||
+ | }} | ||
+ | Example: [http://toxbanktest1.opentox.org:8080/toxbank/user?new=true http://toxbanktest1.opentox.org:8080/toxbank/user] | ||
+ | === cURL example === | ||
+ | curl -X POST -H 'subjectid:TOKEN' -H 'Content-Type:application/x-www-form-urlencoded' \ | ||
+ | -d 'username=VALUE' -d 'title=VALUE' -d 'firstname=VALUE' -d 'lastname=VALUE' \ | ||
+ | -d 'institute=VALUE' -d 'weblog=VALUE' -d 'homepage=VALUE' http://toxbanktest1.opentox.org:8080/toxbank/user | ||
− | + | ==PUT: Update an user == | |
+ | {{REST Operations | ||
+ | |REST_op_description=Updates the user properties | ||
+ | |REST_resource=User | ||
+ | |REST_op_method=PUT | ||
+ | |REST_op_uri=/user/{id} | ||
+ | |REST_op_params=(see cURL examples) | ||
+ | |REST_header_param=subjectid:SECURITY-TOKEN | ||
+ | |REST_op_mime_input=application/x-www-form-urlencoded | ||
+ | |REST_op_result=Task representation in supported MIME formats | ||
+ | |REST_op_mime_output=application/rdf+xml;text/n3;text/uri-list | ||
+ | |REST_op_status=200,202,400,401,402,403,500 | ||
+ | }} | ||
+ | === cURL example === | ||
+ | curl -X PUT -H 'subjectid:TOKEN' -H 'Content-Type:application/x-www-form-urlencoded' \ | ||
+ | -d 'email=VALUE' -d 'title=VALUE' -d 'firstname=VALUE' -d 'lastname=VALUE' \ | ||
+ | -d 'institute=VALUE' -d 'weblog=VALUE' -d 'homepage=VALUE' http://toxbanktest1.opentox.org:8080/toxbank/user/{id} | ||
+ | ==DELETE: Delete an user == | ||
+ | {{REST Operations | ||
+ | |REST_op_description=Removes an existing user | ||
+ | |REST_resource=User | ||
+ | |REST_op_method=DELETE | ||
+ | |REST_op_uri=/user/{id} | ||
+ | |REST_op_params=none | ||
+ | |REST_header_param=subjectid:SECURITY-TOKEN | ||
+ | |REST_op_mime_input=none | ||
+ | |REST_op_result=Task representation in supported MIME formats | ||
+ | |REST_op_mime_output=application/rdf+xml;text/n3;text/uri-list | ||
+ | |REST_op_status=200,202,400,401,402,403,500 | ||
+ | }} | ||
+ | === cURL example === | ||
+ | curl -X DELETE -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/user/U2 | ||
+ | |||
+ | == GET: Retrieve Protocols by User == | ||
+ | Same as [[API_Protocol:RetrieveList]], but filtered by the user. | ||
{{HasOperation |id=User:RetrieveProtocols}} | {{HasOperation |id=User:RetrieveProtocols}} | ||
− | == Retrieve | + | === cURL example === |
+ | curl -X GET -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/user/U2/protocol | ||
+ | |||
+ | |||
+ | == GET: Retrieve Projects by User == | ||
+ | |||
+ | |||
+ | === cURL example === | ||
+ | curl -X GET -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/user/U2/project | ||
+ | |||
+ | |||
+ | == GET: Retrieve Organisation by User == | ||
+ | |||
+ | |||
+ | === cURL example === | ||
+ | curl -X GET -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/user/U2/organisation | ||
+ | |||
+ | |||
+ | == Add project/organisation to the user profile == | ||
+ | |||
+ | === cURL example === | ||
+ | curl -X POST -H 'subjectid:TOKEN' -H 'Content-Type:application/x-www-form-urlencoded' -d 'organisation_uri=ORGANISATION_URI' http://toxbanktest1.opentox.org:8080/toxbank/user/U2/organisation | ||
+ | |||
+ | |||
+ | == Remove project/organisation from the user profile == | ||
+ | |||
+ | === cURL example === | ||
+ | curl -X DELETE -H 'subjectid:TOKEN' -H 'Content-Type:application/x-www-form-urlencoded' http://toxbanktest1.opentox.org:8080/toxbank/user/U2/organisation/G1 | ||
+ | |||
+ | == GET: Retrieve Studies by User == | ||
Same as [[API_Study:RetrieveList]], but filtered by the user. | Same as [[API_Study:RetrieveList]], but filtered by the user. | ||
Line 32: | Line 119: | ||
{{HasOperation |id=User:RetrieveStudies}} | {{HasOperation |id=User:RetrieveStudies}} | ||
− | == | + | == GET: Retrieve alerts by User == |
{{HasOperation |id=User:RetrieveAlerts}} | {{HasOperation |id=User:RetrieveAlerts}} | ||
+ | === cURL example === | ||
+ | curl -X GET -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/user/U2/alert | ||
+ | |||
+ | = Security = | ||
+ | |||
+ | ==== Only a logged in user is allowed to modify content under its URI /user/{id} ==== | ||
+ | |||
+ | User and author information can be retrieved by members of groups 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%2Fuser here]. | ||
+ | |||
+ | ==== Only an admin user allowed to create new users at /user ==== | ||
+ | |||
+ | == Registered users== | ||
+ | Should have URI in Toxbank system, and assigned LDAP username. LDAP/OpenAM backend to be synced with the User service. | ||
+ | |||
+ | == Non-registered users== | ||
+ | Could have an user URI in Toxbank system, but not LDAP username | ||
+ | |||
+ | = RDF representation = | ||
− | = | + | == Stable version == |
+ | [http://jenkins.toxbank.net/job/production-toxbank-api-beans/ws/target/test-classes/net.toxbank.client.resource.User.full.n3 RDF 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/net.toxbank.client.resource.User.full.n3 RDF/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/net.toxbank.client.resource.User.full.n3 RDF/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 format == |
− | ... | + | <pre> |
+ | <?xml version="1.0"?> | ||
+ | <!DOCTYPE rdf:RDF [ | ||
+ | <!ENTITY tb 'http://onto.toxbank.net/api/'> | ||
+ | <!ENTITY foaf 'http://xmlns.com/foaf/0.1/'> | ||
+ | <!ENTITY xsd 'http://www.w3.org/2001/XMLSchema#'> | ||
+ | <!ENTITY tbo 'http://toxbanktest1.opentox.org:8080/toxbank/organisation/'> | ||
+ | <!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: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:tb="&tb;"> | ||
+ | <tb:Project rdf:about="&tbpt;G1"> | ||
+ | <tb:hasProjectMember> | ||
+ | <foaf:Person rdf:about="&tbu;U2"> | ||
+ | <foaf:holdsAccount> | ||
+ | <foaf:OnlineAccount rdf:about="mailto:guest@example.com"> | ||
+ | <foaf:accountName rdf:datatype="&xsd;string">guest@example.com</foaf:accountName> | ||
+ | <foaf:accountServiceHomepage rdf:datatype="&xsd;string" | ||
+ | >mailto</foaf:accountServiceHomepage> | ||
+ | </foaf:OnlineAccount> | ||
+ | </foaf:holdsAccount> | ||
+ | <tb:hasAccount rdf:datatype="&xsd;string">guest</tb:hasAccount> | ||
+ | <foaf:family_name rdf:datatype="&xsd;string">Guest</foaf:family_name> | ||
+ | <foaf:givenname rdf:datatype="&xsd;string">Guest</foaf:givenname> | ||
+ | </foaf:Person> | ||
+ | </tb:hasProjectMember> | ||
+ | <tb:hasAccount rdf:datatype="&xsd;string">partner</tb:hasAccount> | ||
+ | <dcterms:title rdf:datatype="&xsd;string">OpenTox</dcterms:title> | ||
+ | </tb:Project> | ||
+ | </rdf:RDF> | ||
+ | </pre> |
Latest revision as of 14:06, 1 October 2014
User |
---|
An User is a REST resource,representing users from SEURAT cluster, or external users. An User is identified by its URI, and may be assigned an LDAP user name. The LDAP user name should be one of the existing ToxBank LDAP accounts and accessible via ToxBank OpenAM. External users may or may not be assigned an LDAP user name.
A Protocol is always associated with a single user, considered its owner, and the protocol representation includes a link to the owner URI. The owner URI should be an user with a valid LDAP user name. The protocol owner is assigned automatically, when the protocol is uploaded by a logged-in user. Non registered users are not allowed to upload protocols.
A Protocol may be associated with one or more users, considered its authors. The protocol representation includes links to the author URIs.
REST interface
GET: Retrieve users
Description | Retrieve list of users |
---|---|
Resource | User |
Method | GET |
URI | /user |
Parameters | none, or ?search=prefix_of_firstname_or_lastname or paging parameters: page, pagesize or ?username=USERNAME |
Header Parameters | subjectid:SECURITY-TOKEN |
Media Type (input) | none |
Results | The project representation in supported media type |
Media Type (output) | application/rdf+xml;text/n3;text/uri-list |
Status code | 200,400,401,402,403 |
Links: Page, Edit with form
Example: http://toxbanktest1.opentox.org:8080/toxbank/user
cURL example
curl -X GET -H 'Accept:text/uri-list' -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/user
curl -X GET -H 'Accept:application/rdf+xml' -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/user?search=J
curl -X GET -H 'Accept:application/rdf+xml' -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/user?username=guest
curl -X GET -H 'Accept:text/uri-list' -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/user?page=0&pagesize=5
GET: Retrieve user details
Description | Retrieve user details |
---|---|
Resource | User |
Method | GET |
URI | /user/{obfuscated_id} |
Parameters | none |
Header Parameters | subjectid:SECURITY-TOKEN |
Media Type (input) | none |
Results | The user representation in supported media type |
Media Type (output) | application/rdf+xml;text/n3;text/uri-list |
Status code | 200,400,401,402,403 |
Links: Page, Edit with form
cURL example
curl -X GET -H 'Accept:application/rdf+xml' -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/user/U1
POST: Create an User
Description | Creates an user |
---|---|
Resource | User |
Method | POST |
URI | /user |
Parameters | (see the 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) | application/rdf+xml;text/n3;text/uri-list |
Status code | 200,202,400,401,402,403,500 |
Example: http://toxbanktest1.opentox.org:8080/toxbank/user
cURL example
curl -X POST -H 'subjectid:TOKEN' -H 'Content-Type:application/x-www-form-urlencoded' \ -d 'username=VALUE' -d 'title=VALUE' -d 'firstname=VALUE' -d 'lastname=VALUE' \ -d 'institute=VALUE' -d 'weblog=VALUE' -d 'homepage=VALUE' http://toxbanktest1.opentox.org:8080/toxbank/user
PUT: Update an user
Description | Updates the user properties |
---|---|
Resource | User |
Method | PUT |
URI | /user/{id} |
Parameters | (see cURL examples) |
Header Parameters | subjectid:SECURITY-TOKEN |
Media Type (input) | application/x-www-form-urlencoded |
Results | Task representation in supported MIME formats |
Media Type (output) | application/rdf+xml;text/n3;text/uri-list |
Status code | 200,202,400,401,402,403,500 |
cURL example
curl -X PUT -H 'subjectid:TOKEN' -H 'Content-Type:application/x-www-form-urlencoded' \ -d 'email=VALUE' -d 'title=VALUE' -d 'firstname=VALUE' -d 'lastname=VALUE' \ -d 'institute=VALUE' -d 'weblog=VALUE' -d 'homepage=VALUE' http://toxbanktest1.opentox.org:8080/toxbank/user/{id}
DELETE: Delete an user
Description | Removes an existing user |
---|---|
Resource | User |
Method | DELETE |
URI | /user/{id} |
Parameters | none |
Header Parameters | subjectid:SECURITY-TOKEN |
Media Type (input) | none |
Results | Task representation in supported MIME formats |
Media Type (output) | application/rdf+xml;text/n3;text/uri-list |
Status code | 200,202,400,401,402,403,500 |
cURL example
curl -X DELETE -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/user/U2
GET: Retrieve Protocols by User
Same as API_Protocol:RetrieveList, but filtered by the user.
Description | Retrieves list of protocols, including metadata, filtered by the user |
---|---|
Resource | User |
Method | GET |
URI | /user/{obfuscated_id}/protocols |
Parameters | TBD , search parameters to query/filter protocols |
Header Parameters | subjectid:SECURITY-TOKEN |
Media Type (input) | none |
Results | List of protocols in supported MIME formats |
Media Type (output) | text/uri-list, RDF, JSON, XML |
Status code | 200, 400, 401, 402, 403 |
Links: Page, Edit with form
cURL example
curl -X GET -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/user/U2/protocol
GET: Retrieve Projects by User
cURL example
curl -X GET -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/user/U2/project
GET: Retrieve Organisation by User
cURL example
curl -X GET -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/user/U2/organisation
Add project/organisation to the user profile
cURL example
curl -X POST -H 'subjectid:TOKEN' -H 'Content-Type:application/x-www-form-urlencoded' -d 'organisation_uri=ORGANISATION_URI' http://toxbanktest1.opentox.org:8080/toxbank/user/U2/organisation
Remove project/organisation from the user profile
cURL example
curl -X DELETE -H 'subjectid:TOKEN' -H 'Content-Type:application/x-www-form-urlencoded' http://toxbanktest1.opentox.org:8080/toxbank/user/U2/organisation/G1
GET: Retrieve Studies by User
Same as API_Study:RetrieveList, but filtered by the user.
Description | Retrieves list of studies, including metadata, filtered by the user |
---|---|
Resource | User |
Method | GET |
URI | /user/{obfuscated_id}/study |
Parameters | TBD , search options to query/filter studies |
Header Parameters | subjectid:SECURITY-TOKEN |
Media Type (input) | none |
Results | List of studies in supported Media Type formats |
Media Type (output) | text/uri-list, RDF, JSON, XML |
Status code | 200,400,401,402,403 |
Links: Page, Edit with form
GET: Retrieve alerts by User
Description | Retrieves list of alerts, filtered by the user |
---|---|
Resource | User |
Method | GET |
URI | /user/{obfuscated_id}/alerts |
Parameters | TBD , search options to query/filter alerts |
Header Parameters | subjectid:SECURITY-TOKEN |
Media Type (input) | none |
Results | List of alerts in supported Media Type formats |
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 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/user/U2/alert
Security
Only a logged in user is allowed to modify content under its URI /user/{id}
User and author information can be retrieved by members of groups scrtox,hemibio,notox,cosmos,toxbank,detective,sep.
The policies can be browsed here.
Only an admin user allowed to create new users at /user
Registered users
Should have URI in Toxbank system, and assigned LDAP username. LDAP/OpenAM backend to be synced with the User service.
Non-registered users
Could have an user URI in Toxbank system, but not LDAP username
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 format
<?xml version="1.0"?> <!DOCTYPE rdf:RDF [ <!ENTITY tb 'http://onto.toxbank.net/api/'> <!ENTITY foaf 'http://xmlns.com/foaf/0.1/'> <!ENTITY xsd 'http://www.w3.org/2001/XMLSchema#'> <!ENTITY tbo 'http://toxbanktest1.opentox.org:8080/toxbank/organisation/'> <!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: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:tb="&tb;"> <tb:Project rdf:about="&tbpt;G1"> <tb:hasProjectMember> <foaf:Person rdf:about="&tbu;U2"> <foaf:holdsAccount> <foaf:OnlineAccount rdf:about="mailto:guest@example.com"> <foaf:accountName rdf:datatype="&xsd;string">guest@example.com</foaf:accountName> <foaf:accountServiceHomepage rdf:datatype="&xsd;string" >mailto</foaf:accountServiceHomepage> </foaf:OnlineAccount> </foaf:holdsAccount> <tb:hasAccount rdf:datatype="&xsd;string">guest</tb:hasAccount> <foaf:family_name rdf:datatype="&xsd;string">Guest</foaf:family_name> <foaf:givenname rdf:datatype="&xsd;string">Guest</foaf:givenname> </foaf:Person> </tb:hasProjectMember> <tb:hasAccount rdf:datatype="&xsd;string">partner</tb:hasAccount> <dcterms:title rdf:datatype="&xsd;string">OpenTox</dcterms:title> </tb:Project> </rdf:RDF>
HasOperation | RetrieveList +, Details +, RetrieveProtocols +, RetrieveStudies + and RetrieveAlerts + |