Users Ajax Endpoints¶
Intro¶
The Users package exposes some AJAX endpoints to allow your Erdiko Application to interact with the underlying service models.
Some of these endpoints require an authenticated user and will be noted as such.
Unique Response Object Valuess¶
All of these AJAX endpoints return a JSON formatted response and contain some unique responses as well as common values indicating the success or failure of the request.
Here is a brief list of the common response variables:
- method
- String indicating the requested method
- success
- Boolean flag set to true for a successful login attempt, else this is false
- error_code
- Error code if the login attempt is unsuccessful
- error_message
- Error message if the login attempt is unsuccessful
Here is an example of a successful request response:
{
"method": "login",
"success": true,
"error_code": 0,
"error_message": "",
"token": "1234asdf",
}
If a request is unsuccessful, we return flags and messaging explaining the error. Here is an example:
{
"method": "login",
"success": false,
"error_code": 1,
"error_message": "Invalid email or password provided; User was not found"
}
User Authentication¶
postLogin¶
POST endpoint that logs a user in via the JWTAuthenticator (erdiko\authenticate\services\JWTAuthenticator) from the Erdiko\Authenticate package.
After successfully validating the user's email and password with the JWTAuthenticator class, the AJAX response will return a JWT token.
URL
[ROUTE]/login/
Required Parameters
- email
- User's email
- password
- User's password
Unique Response Object Values
- token
- JWT token generated by the JWTAuthenticator class
Example Response
{
"method": "login",
"success": true,
"error_code": 0,
"error_message": "",
"token": "1234asdf",
}
getLogout¶
GET endpoint that logs a user out via the BasicAuthenticator (erdiko\authenticate\services\BasicAuthenticator) from the Erdiko\Authenticate package.
URL
[ROUTE]/logout/
Required Parameters
n/a
Unique Response Object Values
n/a
Example Response
{
"method": "logout",
"success": true,
"error_code": 0,
"error_message": ""
}
postChangepass¶
POST endpoint that attempts to change a password for an existing user via the BasicAuthenticator (erdiko\authenticate\services\BasicAuthenticator) from the Erdiko\Authenticate package.
This method will return false if the user's email and password do not match an existing user.
URL
[ROUTE]/changepass/
Required Parameters
- email
- Existing user's email
- currentpass
- Current user's password
- newpass
- New user's password
Unique Response Object Values
n/a
Example Response
{
"method": "changepass",
"success": true,
"error_code": 0,
"error_message": ""
}
postForgotpass¶
POST endpoint that will send a "Reset Password" email to a user after resetting the user's email to a random string.
This method will return false if the email is not found in the user database.
URL
[ROUTE]/forgotpass/
Required Parameters
- email
- Existing user's email
Unique Response Object Values
n/a
Example Response
{
"method": "forgotpass",
"success": true,
"error_code": 0,
"error_message": ""
}
Role¶
All Role AJAX routes require an authenticated user, and will check for a valid JWT bearer token.
getRoles¶
GET endpoint that returns a list of active roles found in the DB and a count of active users associated with the role.
URL
[ROUTE]/roles/
Required Parameters
n/a
Unique Response Object Values
- roles
- Array of existing roles
Example Response
{
"method": "roles",
"success": true,
"error_code": 0,
"error_message": "",
"roles": [
{
"id": 42,
"name": "Customer",
"active": true,
"users": 30
},
{
"id": 43,
"name": "Admin",
"active": true,
"users": 3
}
]
}
getRole¶
GET endpoint that returns a JSON representation of a valid Role for a provided ID along with a list of users associate with this role.
URL
[ROUTE]/role/
Required Parameters
n/a
Unique Response Object Values
- role
- Object representation of the role found for the provided ID
Example Response
{
"method": "role",
"success": true,
"error_code": 0,
"error_message": "",
"role": {
"id": 43,
"name": "Admin",
"active": true,
"users": [
{
"id": 2,
"email": "john.smith@example.com",
"name": "John Smith"
}
]
}
}
postCreaterole¶
POST endpoint that create a Role record with the provided values.
URL
[ROUTE]/createrole/
Required Parameters
- name
- string representing the new role name
- active
- boolean flag set to TRUE if the new role is active, false if inactive
Unique Response Object Values
- role
- Object representation of the role created with the request
Example Response
{
"method": "createrole",
"success": true,
"error_code": 0,
"error_message": "",
"role": {
"id": 43,
"name": "Admin",
"active": true,
"users": [
{
"id": 2,
"email": "john.smith@example.com",
"name": "John Smith"
}
]
}
}
postUpdaterole¶
POST endpoint that updates a Role record for a provided ID with the provided value.
URL
[ROUTE]/updaterole/
Required Parameters
- id
- id for the role record to update
- name
- string representing the role name to update
- active
- boolean flag set to TRUE if the role is active, false if inactive
Unique Response Object Values
- role
- Object representation of the role created with the request
Example Response
{
"method": "updaterole",
"success": true,
"error_code": 0,
"error_message": "",
"role": {
"id": 43,
"name": "Admin",
"active": true,
"users": [
{
"id": 2,
"email": "john.smith@example.com",
"name": "John Smith"
}
]
}
}
postDeleterole¶
POST endpoint that deletes a Role based on a provided ID.
URL
[ROUTE]/deleterole/
Required Parameters
- id
- id for the role record to update
Unique Response Object Values
- role
- ID of the role that was deleted
Example Response
{
"method": "deleteerole",
"success": true,
"error_code": 0,
"error_message": "",
"role": 43
}
User¶
All User AJAX routes require an authenticated user, and will check for a valid JWT bearer token.
postRegister¶
POST endpoint that creates a User record with the provided values. This mehod returns false if the provided email is already found in the database.
URL
[ROUTE]/register/
Required Parameters
- email
- new user's email
- password
- new user's password
- role
- id for the new user's role, must be a valid role id
- name
- new user's name
Unique Response Object Values
- user
- JSON representation of the new user created by the request
Example Response
{
"method": "register",
"success": true,
"error_code": 0,
"error_message": "",
"user": {
"id": 43,
"email": "foo@email.com"
"role": 1,
"name": "John Smith"
"last_login": "2017-07-01 00:00:01"
"gateway_customer_id": ""
}
}
getList¶
GET endpoint that returns a list of active users found in the DB.
URL
[ROUTE]/list/
Required Parameters
n/a
Optional Parameters¶
- page
- Integer indicating the requested page. Defaults to 0.
- pagesize
- Integer indicating the requested number of records to return. Defaults to 100.
- sort
- String indicating the column to sort the records. Defaults to "id"
- direction
- String indicating the direction to be used when sorting the records. Defaults to "desc"
Unique Response Object Values
- users
- Object representation of the role created with the request
Example Response
{
"method": "list",
"success": true,
"error_code": 0,
"error_message": "",
"users": [
{
"id": 2,
"email": "john.smith@example.com",
"name": "John Smith"
}
]
}
getRetrieve¶
GET endpoint that returns a JSON representation of a valid User for a provided ID along with a list of users associate with this role.
URL
[ROUTE]/retrieve/
Required Parameters
- id
- An ID for an existing user
Unique Response Object Values
- user
- Object representation of the found for this ID
Example Response
{
"method": "retrieve",
"success": true,
"error_code": 0,
"error_message": "",
"user": {
"id": 43,
"email": "foo@email.com"
"role": 1,
"name": "John Smith"
"last_login": "2017-07-01 00:00:01"
"gateway_customer_id": ""
}
}
postUpdate¶
POST endpoint that updates a user record for a provided ID with the provided values
URL
[ROUTE]/update/
Required Parameters
- id
- An id for an existing user
Optional Parameters¶
None of these parameters are required, but will update the user record if any or all are provided.
- name
- New name value for the existing user
- email
- new email for the existing user
- password
- New password for the existing user
- role
- New role ID for the existing user
- gateway_customer_id
- Gateway ID for the existing user
Unique Response Object Values
- user
- Object representation of the user updated by this request
Example Response
{
"method": "update",
"success": true,
"error_code": 0,
"error_message": "",
"user": {
"id": 43,
"email": "foo@email.com"
"role": 1,
"name": "John Smith"
"last_login": "2017-07-01 00:00:01"
"gateway_customer_id": ""
}
}
getCancel¶
GET method to deactivate a user for a provided ID.
URL
[ROUTE]/cancel/
Required Parameters
- id
- An id for an existing user
Unique Response Object Values
- user
- ID for the user that was deactivated
Example Response
{
"method": "cancel",
"success": true,
"error_code": 0,
"error_message": "",
"user": 42
}
postAddUserEvent¶
POST method to create a new event Log for current user
URL
[ROUTE]/adduserevent/
Required Parameters
- event
- string indicating the event type
Optional Parameters¶
None of these parameters are required, but will update the user record if any or all are provided.
- event_data
- JSON object containing event log data
- event_source
- String indicating the event log source, defaults to "front_end"
Unique Response Object Values
- log
- Object representing the user logged event
- user_id
- ID for the user that just had an event logged
Example Response
{
"method": "adduserevent",
"success": true,
"error_code": 0,
"error_message": "",
"log": {
"event": "button-click",
"event_data": "{'id': 2}",
"created_at": "2017-07-01 00:00:01"
},
"user_id": 42
}
Admin User¶
All Admin User AJAX routes require an authenticated Admin User, and will check for a valid JWT bearer token.
postCreate¶
POST method to create a new user record. Returns false if the email exists in the database already.
URL
[ROUTE]/create/
Required Parameters
- email
- new user's email
- password
- new user's password
- role
- id for the new user's role, must be a valid role id
- name
- new user's name
Unique Response Object Values
- user
- JSON representation of the new user created by the request
Example Response
{
"method": "create",
"success": true,
"error_code": 0,
"error_message": "",
"user": {
"id": 43,
"email": "foo@email.com"
"role": 1,
"name": "John Smith"
"last_login": "2017-07-01 00:00:01"
"gateway_customer_id": ""
}
}
getList¶
GET method to return a paginated list of users
URL
[ROUTE]/list/
Required Parameters
n/a
Optional Parameters¶
- page
- Integer indicating the requested page. Defaults to 0.
- pagesize
- Integer indicating the requested number of records to return. Defaults to 100.
- sort
- String indicating the column to sort the records. Defaults to "id"
- direction
- String indicating the direction to be used when sorting the records. Defaults to "desc"
Unique Response Object Values
- users
- Array of users found by this request
Example Response
{
"method": "list",
"success": true,
"error_code": 0,
"error_message": "",
"users": [
{
"id": 2,
"email": "john.smith@example.com",
"name": "John Smith"
}
...
]
}
getRetrieve¶
GET Method to return a single user record based on a provided ID
URL
[ROUTE]/retrieve/
Required Parameters
- id
- An ID for an existing user
Unique Response Object Values
- user
- Object representation of the found for this ID
Example Response
{
"method": "retrieve",
"success": true,
"error_code": 0,
"error_message": "",
"user": {
"id": 43,
"email": "foo@email.com"
"role": 1,
"name": "John Smith"
"last_login": "2017-07-01 00:00:01"
"gateway_customer_id": ""
}
}
postUpdate¶
POST method to update an existing user record based on the provided parameters
URL
[ROUTE]/update/
Required Parameters
- id
- An id for an existing user
Optional Parameters¶
None of these parameters are required, but will update the user record if any or all are provided.
- name
- New name value for the existing user
- email
- new email for the existing user
- password
- New password for the existing user
- role
- New role ID for the existing user
- gateway_customer_id
- Gateway ID for the existing user
Unique Response Object Values
- user
- Object representation of the found for this ID
Example Response
{
"method": "update",
"success": true,
"error_code": 0,
"error_message": "",
"user": {
"id": 43,
"email": "foo@email.com"
"role": 1,
"name": "John Smith"
"last_login": "2017-07-01 00:00:01"
"gateway_customer_id": ""
}
}
postDelete¶
POST method to delete a user based on a provided ID
URL
[ROUTE]/delete/
Required Parameters
- id
- id for the user record to delete
Unique Response Object Values
- user
- ID of the user that was deleted
Example Response
{
"method": "delete",
"success": true,
"error_code": 0,
"error_message": "",
"user": 43
}
getUserActivity¶
GET method to return the event logs for a provided user if an ID is provided, or the current user if the user ID is not provided.
URL
[ROUTE]/eventlogs/
Required Parameters
n/a
Optional Parameters¶
- user_id
- ID for an existing user
- page
- Integer indicating the requested page. Defaults to 0.
- page_size
- Integer indicating the requested number of records to return. Defaults to 100.
- sort
- String indicating the column to sort the records. Defaults to "created_at"
- direction
- String indicating the direction to be used when sorting the records. Defaults to "asc"
Unique Response Object Values
- logs
- Array of user log events
Example Response
{
"method": "useractivity",
"success": true,
"error_code": 0,
"error_message": "",
"logs": [
{
"id": 2,
"user_id": 42, "event": "button-click",
"email": "{'foo': true}",
"created_at": "2017-07-01 00:00:01"
}
...
]
}
getEventLogs¶
GET method to return an array of all user event logs
URL
[ROUTE]/eventlogs/
Required Parameters
n/a
Optional Parameters¶
- page
- Integer indicating the requested page. Defaults to 0.
- page_size
- Integer indicating the requested number of records to return. Defaults to 100.
- sort
- String indicating the column to sort the records. Defaults to "created_at"
- direction
- String indicating the direction to be used when sorting the records. Defaults to "asc"
Unique Response Object Values
- logs
- Array of user log events
Example Response
{
"method": "geteventlogs",
"success": true,
"error_code": 0,
"error_message": "",
"logs": [
{
"id": 2,
"user_id": 42, "event": "button-click",
"email": "{'foo': true}",
"created_at": "2017-07-01 00:00:01"
}
...
]
}
postChangepass¶
POST method to update an existing user's password
URL
[ROUTE]/changepass/
Required Parameters
- email OR id
- Existing user's email or ID. one of these values is required
- newpass
- New user's password
Unique Response Object Values
n/a
Example Response
{
"method": "changepass",
"success": true,
"error_code": 0,
"error_message": ""
}