8bitology API - Users

Overview

The purpose of the user management functions are for the creation and maintenance of users either within a game or a lobby type application. Many of these functions are purely optional if a game author doesn't intend to include lobby functionality within the game itself - as the website provides basic lobby functionality anyway.

For security reasons, some of the functions such as registering a new user or changing passwords make use of emails to send confirmations rather than purely trusting the API.

The typical flow for the creation of a new user is as follows:
1. The application calls user_register which causes a registration email to be sent to the user.
2. The user who registered clicks on the user_confirm link within their received email which confirms their registration. A confirmation email is sent the user so they can know for future reference, their secret user id.

The typical flow for the changing of a user's password is as follows:
1. The application calls user_changepassword which causes a change password email to be sent to the user.
2. The user receives the email can then click on the user_confirmpassword link within their received email which confirms their password change.

Logging In

It is actually optional to login and logout. If an application chooses to provide login and logout facilities, it can do so by calling user_login which returns the user's secret user id. This also changes the status to online. Likewise, a game could logout the user when they have finished playing by calling user_logout that changes the status of the user to offline.

Although sometimes logging in and loggout out is desirable, rather than forcing the user to do this every time they play a game, you can store the user's secret user id, and if you had previously stored it when they run your game, you can alternatively just bring them online or offline by calling user_setstatus.

Listing Users

You can list all users with user_alllist, alternatively if you only want to list online or offline, or list them separately, you can do so with user_statuslist.

User Management API functions.

function: user_confirm
parameters: <secretuid>
response: true or false
description: Confirm self registration.

function: user_changepassword
parameters: <secretuid>,<oldpassword>,<newpassword>
response: true or false, email sent
description: Changes the users password.

function: user_confirmpassword
parameters: <secretuid>
response: true or false, email sent
description: Confirm a forgotten password reset.

function: user_forgotpassword
parameters: <emailaddress>
response: true or false, email sent
description: A user has forgotten their password.

function: user_forgotsecretuid
parameters: <secretuid>
response: true or false, email sent
description: A user has forgotten their secretuid. At a glance this looks odd they need the secretuid to be able to state they forgot it, but they can login using their name and password which returns their secretuid. The two methods of authentication are to cater client-side storage of the secretuid if required so the user doesnt always need to login.

function: user_login
parameters: <name>, <password>
response: <secretuid> or <error>
description: The user will be logged in.

function: user_logout
parameters: <secretuid>
response: true or false, email sent
description: User will be logged out.

function: user_register
parameters: <emailaddress>, <name>, <password>
response: true or false, email sent
description: Register a new user.

function: user_resetuid
parameters: <emailaddress>
response: true or false, email sent
description: A user wants to reset their secretuid. only admin can do this.

function: user_setabout
parameters: <secretuid>, <text>
response: true or false
description: Set selfs about.

function: user_setstatus
parameters: <secretuid>, <status>
response: true or false
description: Set a selfs status.

function: user_unregister
parameters: <secretuid>
response: true or false
description: Unregister self. only admin can do this.

General User API functions.

function: user_alllist
parameters: <secretuid>, <offset>, <limit>
response: list of <uid>, <name>, <status>, <statusdescription>
description: List all active users.

function: user_getabout
parameters: <secretuid>, <uid>
response: <text>
description: Get a users about.

function: user_getstatus
parameters: <secretuid>, <uid>
response: <name>, <statuscode>, <statusdescription>
description: Get a users status.

function: user_statuslist
parameters: <secretuid>, <status>, <offset>, <limit>
response: list of <uid>, <name>, <status>
description: List users with a specified status.