\BlueLaTeX

Real-Time Collaborative Document Edition

View project onGitHub

User API

Api Summary

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

Get User List

Method: GET

Path: /<api>/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: /<api>/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: /<api>/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: /<api>/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: /<api>/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: /<api>/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 modify 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 Available Permission Sets

Method: GET

Path: /<api>/users/<name>/permissions

Parameters:

Name Type Description
names_only boolean Whether to return the set of permission names optional. Default is false.

Response:

Code Value Meaning Headers
200 permission object The permission data ETag contains the revision of the permission data (to be used when modifying them)
500 error object Something wrong happened on the server side N/A

The permission data object is as follows:

{
  "public": {
    "author": ["read", "write", ...],
    "reviewer": ["read"],
    "guest": [],
    "other": [],
    "anonymous": [],
  }
}

Modify Custom Permissions

Method: PATCH

Path: /<api>/users/<name>/permissions

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

Body: A Json Patch document as per RFC-6902 that modifies the permission 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 permission data was successfully modified ETag contains the new revision of the permission 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 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: /<api>/users/<name>/papers

Response:

Code Value Meaning
200 user role object The array of roles and 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 modify it.

Delete User

Method: DELETE

Path: /<api>/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