Web API: Users - mapto/sprks GitHub Wiki

Accounts

POST /api/user/account

Sets the user_id session data to mark the client as logged in

It's only of use to the browser interface, since REST architectures are, by their nature, stateless, and do not require session keeping.

Request

Takes the standard authorization mechanism (which checks for HTTP headers), and if the returned user_id is valid, sets a user_id value in the session.

Sample

Does not take any data - relies on HTTP Authorization header.

Response

While there would normally only be one message returned, the client should account for instances where this is not the case.

Sample

{
  'success': False,
  'messages': ['Invalid username/password']
}

PUT /api/user/account/{Username} (Public)

Registers a new user with specified username, inserting details into database.

Request

The server will check that the username and email aren't empty for data integrity reasons. However, client should also verify this (along with the password field).

The session will only automatically login the user being created if the (optional) autologin attribute in the attached JSON object is explicitly set to true. If left unset (or set as false), the server will assume a standard REST call and session data will not be updated.

Sample

{
  'password': 'mypassword',
  'email': '[email protected]',
  'autologin': true
}

Response

While there would normally only be one message returned, the client should account for instances where this is not the case.

Sample

{
  'success': True,
  'messages': ['User registered']
}

Passwords

PUT /api/user/password/{User ID} (Public - uses one-off token)

Changes the password for user with the specified ID.

Request

Within the JSON object, the token is a randomly generated string of length 56 consisting of hexadecimal characters. This token will be used to lookup the database containing password recovery requests, and if validated for the specified user, allows the password to be changed even if not authorized by conventional means. For standard password changes, the token value can be omitted or set to empty string.

The session will only automatically login the user being modified if the (optional) autologin attribute in the attached JSON object is explicitly set to true. If left unset (or set as false), the server will assume a standard REST call and session data will not be updated.

Sample

{
  'password': 'mypassword',
  'token': '30d08fed7c89a22d4cf1609826266ffce1259387c19930653a8498a9',
  'autologin': true
}

Response

While there would normally only be one message returned, the client should account for instances where this is not the case.

Sample

{
  'success': True,
  'messages': ['Password changed']
}

POST /api/user/password/{User ID} (Public)

Generates a password recovery request for specified user ID.

This method generates a random token, which is stored in the database and emailed to the specified user. This token can then be used later to change the user's password without standard authorization.

Request

While the official approach takes the user_id as an argument, this method also accepts the username as the argument, if uid_type is set to 'username' in the attached JSON object. The argument will be parsed as the user_id if uid_type is set to 'user_id', empty string, or not specified (or no JSON object is attached). All other values will cause an error.

Sample

{
  'uid_type': 'username'
}

Response

While there would normally only be one message returned, the client should account for instances where this is not the case.

Sample

{
  'success': True,
  'messages': ['Password recovery email sent']
}