Users Api

Api Summary

Method	Path	Description
GET	/users	Gets list of users
POST	/users	Registers a new user
GET	/users/<name>/reset	Generates a password reset token
POST	/users/<name>/reset	Performs password reset
GET	/users/<name>/info	Gets the user data
PATCH	/users/<name>/info	Modifies the user data
GET	/users/<name>/papers	Gets the list of papers shared with the user
DELETE	/users/<name>	Deletes the authenticated user

Get User List

Method: GET

Path: /users

Parameters:

Name	Type	Description
name	string	The user name, only returns users whose name starts with the given value optional

Response:

Code	Value	Meaning
201	list of user names	The list of matching users
401	error object	User is not authenticated
500	error object	Something wrong happened on the server side and the user list could not be returned

Register User

Method: POST

Path: /users

Parameters:

Name	Type	Description
username	string	The user name mandatory
first_name	string	The user first name mandatory
last_name	string	The user last name mandatory
email_address	string	The user email address mandatory
affiliation	string	The user affiliation (university, company, ...) optional
recaptcha_response_field	string	The ReCaptcha response field optional if no captcha configured on the server, mandatory otherwise
recaptcha_challenge_field	string	The ReCaptcha challenge field optional if no captcha configured on the server, mandatory otherwise

Response:

Code	Value	Meaning
201	true	The user was successfully registered
400	error object	Some parameters are missing
401	error object	The captcha did not verify
409	error object	A user with the same name already exists
500	error object	Something wrong happened on the server side and the user could not be registered

Generate Password Reset Token

Method: GET

Path: /users/<name>/reset

Response:

Code	Value	Meaning
200	true	The password reset token was successfully created and sent
403	error object	Logged in users may not request password reset
500	error object	Something wrong happened on the server side

Perform Password Reset

Method: POST

Path: /users/<name>/reset

Parameters:

Name	Type	Description
reset_token	string	The reset token mandatory
new_password1	string	The new password mandatory
new_password2	string	The new password (repeated) mandatory

Response:

Code	Value	Meaning
200	true	The password was successfully reset
400	error object	Some parameters are missing
500	error object	Something wrong happened on the server side and the action could not be performed

Get User Data

Method: GET

Path: /users/<name>/info

Response:

Code	Value	Meaning	Headers
200	user object	The user data	ETag contains the revision of the user data (to be used when modifying them)
403	error object	Logged in users may not request password reset	N/A
500	error object	Something wrong happened on the server side	N/A

The user object is as follows:

{
  "name": "glambert",
  "first_name": "Gérard",
  "last_name": "Lambert",
  "email": "[email protected]",
  "affiliation": "University of Gnieh"
}

Modify User Data

Method: PATCH

Path: /users/<name>/info

Headers: If-Match contains the revision of the user data to modify (as returned in the ETag header)

Body: A Json Patch document as per RFC-6902 that modifies the user data. A prerequisite is that the structure of the object must not be modified, only the values of standard fields (no new fields, no mandatory field removed, ...)

Response:

Code	Value	Meaning	Headers
200	true	The user data was successfully modified	ETag contains the new revision of the user data after modifications were applied
304	error object	Not enough data were sent to perform modification	N/A
401	error object	User must be authenticated	N/A
403	error object	Not authorized to modifiy the user data	N/A
404	error object	User does not exist	N/A
409	error object	No revision or an obsolete revision was provided in the request	N/A
500	error object	Something wrong happened on the server side and the action could not be performed	N/A

Get User Papers

Returns the list of papers the user is involved into, along with the role for each paper.

Method: GET

Path: /users/<name>/papers

Response:

Code	Value	Meaning
200	user role object	The array of user roles with papers user is involved into
401	error object	User must be authenticated
500	error object	Something wrong happened on the server side

The user rule object is as follows:

{
  "paper": "432f209d21090e09c09b0aa",
  "name": "Efficiently Writing Rest Api Documentation",
  "creation_date": "2014-06-20T17:57:21.902",
  "role": "author"
}

Possible roles are:

• author the user may edit the paper,
• reviewer the user may read the paper but not modifiy it.

Delete User

Method: DELETE

Path: /users/<name>

Parameters:

Name	Type	Description
recaptcha_response_field	string	The ReCaptcha response field optional if no captcha configured on the server, mandatory otherwise
recaptcha_challenge_field	string	The ReCaptcha challenge field optional if no captcha configured on the server, mandatory otherwise

Response:

Code	Value	Meaning
200	true	The user was removed
401	error object	Captcha did not verify or user could not be authenticated
403	error object	The user still owns papers (single author of a paper)
500	error object	Something wrong happened on the server side