User

From ToxBank API Wiki
(Difference between revisions)
Jump to: navigation, search
(Retrieve My Studies)
(cURL example)
 
(28 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
{{REST_resource}}
 
{{REST_resource}}
  
= OpenAM =
+
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.
  
Currently, User details can be retrieved by requesting OpenAM attributes, given a valid token.
+
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.
  
== Java library ==
+
A [[Protocol]] may be associated with one or more users, considered its authors. The protocol representation includes links to the author URIs.
http://vedina.github.com/opentox-aa-cli/
+
 
+
== Ruby library ==
+
...
+
  
 
= REST interface =
 
= REST interface =
  
Would be useful to expose users via URIs, to be able to link various objects to the authors/owners.
+
== GET: Retrieve users ==
The user name should not be in the URI,an approach similar to Google+ can be adopted
+
{{HasOperation |id=User:RetrieveList}}
 +
Example: [http://toxbanktest1.opentox.org:8080/toxbank/user 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
  
  This is my user URI at G+
+
  curl -X GET -H 'Accept:application/rdf+xml' -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/user?search=J
https://plus.google.com/106434626815784595027
+
  
  And here are my posts.
+
  curl -X GET -H 'Accept:application/rdf+xml' -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/user?username=guest
https://plus.google.com/106434626815784595027/posts
+
The content you see will differ, depending on whether you are logged in G+,
+
and whether you are allowed to see particular post.
+
  
== Retrieve users ==
+
curl -X GET -H 'Accept:text/uri-list' -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/user?page=0&pagesize=5
{{HasOperation |id=User:RetrieveList}}
+
  
 +
== GET: Retrieve user details ==
 +
{{HasOperation |id=User:Details}}
 
=== cURL example ===
 
=== cURL example ===
  curl -X GET /user?consortium=ToxBank
+
  curl -X GET -H 'Accept:application/rdf+xml' -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/user/U1
  
== Retrieve user details ==
+
==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 Operations
|REST_op_description=Retrieve user details
+
|REST_op_description=Updates the user properties
|REST_op_method=GET
+
|REST_resource=User
|REST_op_uri=/user/{obfuscated_id}
+
|REST_op_method=PUT
|REST_op_params=TBD, may be used to filter the retrieved info
+
|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_header_param=subjectid:SECURITY-TOKEN
 
|REST_op_mime_input=none
 
|REST_op_mime_input=none
|REST_op_result=content
+
|REST_op_result=Task representation in supported MIME formats
|REST_op_mime_output=multiple formats
+
|REST_op_mime_output=application/rdf+xml;text/n3;text/uri-list
|REST_op_status=200,202,400,401,402,403
+
|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
  
== Retrieve My Protocols ==
+
== GET: Retrieve Protocols by User ==
 
+
 
Same as [[API_Protocol:RetrieveList]], but filtered by the user.
 
Same as [[API_Protocol:RetrieveList]], but filtered by the user.
 
 
{{HasOperation |id=User:RetrieveProtocols}}
 
{{HasOperation |id=User:RetrieveProtocols}}
  
== Retrieve My Studies ==
+
=== 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 56: Line 119:
 
{{HasOperation |id=User:RetrieveStudies}}
 
{{HasOperation |id=User:RetrieveStudies}}
  
== My alerts ==
+
== GET: Retrieve alerts by User ==
  
{{REST Operations
+
{{HasOperation |id=User:RetrieveAlerts}}
|REST_op_description=Retrieves list of alerts, filtered by the user
+
=== cURL example ===
|REST_op_method=GET
+
curl -X GET -H 'subjectid:TOKEN' http://toxbanktest1.opentox.org:8080/toxbank/user/U2/alert
|REST_op_uri=/user/{obfuscated_id}/alerts
+
 
|REST_op_params=TBD , search options to query/filter alerts
+
= Security =
|REST_header_param=subjectid:SECURITY-TOKEN
+
 
|REST_op_mime_input=none
+
==== Only a logged in user is allowed to modify content under its URI /user/{id} ====
|REST_op_result=List of alerts in supported Media Type formats
+
 
|REST_op_mime_output=text/uri-list, RDF, JSON, XML
+
User and author information can be retrieved by members of groups scrtox,hemibio,notox,cosmos,toxbank,detective,sep.
|REST_op_status=200,400,401,402,403
+
 
}}
+
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.

Contents

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

RDF N3

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

Alpha test version

RDF/N3

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

Development version

RDF/N3

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>
Personal tools