api Recent Posts

Here we describe the API for user registration. The registration enables a user to register an account in Xhoppe.

User registration

Here is the URL for user registration,

POST /api/v1/users

Expected parameters in the body

• msisdn: The phone number of the user
• username: The username
• password: The password of the user

Sample Request

1
2
3
4
5
6
7
8

POST /api/v1/users


{
  "msisdn": "84932466",
  "username": "Mike Jackson"
  "password": "12345678"
}

Sample Response

1
2
3
4

{
  "msisdn": "84932466",
  "valid_for_authentication": false
}

If register successful, the server returns the following attributes,

• msisdn: The phone number of the user
• valid_for_authentication: Will be false if the user is locked or if the user is not verified yet.

Sample error response

If the register is failed, the server will return an error response, for example, if the email is already taken,

1
2
3
4
5
6
7
8

{
  "error": "Invalid resource. Please fix errors and try again.",
  "errors": {
    "msisdn": [
      "has already been taken"
    ]
  }
}

Verification code

After the user is registered, a SMS will be send to the user, the user needs to input this verification code to be enabled.

POST /api/v1/users/verify

Expected parameters in the body
- msisdn: the phone number
- sms_confirmation_token: The verification code received by the user.

Sample Request

1
2
3
4
5
6

POST /api/v1/users/verify

{
  "msisdn": "1234234"
  "sms_confirmation_token": "2334"
}

Sample Response

1
2
3
4
5
6

{
  "msisdn": "84932466",
  "username": "Mike Jackson",
  "authentication_token": "h-jkDAMwJzrsm-4bvgzw",
  "valid_for_authentication": true
}

If the verification is successful, it will return the authentication_token to the client.

The SMS confirmation token is case insensitive.

Sample error response

If the SMS confirmation token is invalid

1
2
3
4
5
6
7
8

{
  "error": "Invalid resource. Please fix errors and try again.",
  "errors": {
    "sms_confirmation_token": [
      "is invalid"
    ]
}
}

If the SMS confirmation token is expired

1
2
3
4
5
6
7
8

{
  "error": "Invalid resource. Please fix errors and try again.",
  "errors": {
    "sms_confirmation_token": [
      "is expired"
    ]
}
}

After the SMS is sent, the token is valid for 10 minutes.

Resend Verify

If the SMS is sent but the user didn’t confirm. He could invoke ‘Resend Verify’ to send another SMS.

1
2
3
4
5

POST /api/v1/users/resend_verify

{
  "msisdn": "+6584932466"
}

The response should be

1
2
3
4
5
6

{
  "msisdn": "84932466",
  "username": "Mike Jackson",
  "authentication_token": "h-jkDAMwJzrsm-4bvgzw",
  "valid_for_authentication": false
}

Forget password

If the user forgets his password, he could recover by first call Resend Verify API to send a SMS to user.

After the user receives the SMS, he should enter the SMS in a dialog, and the client calls check_sms_token API to check if the token is good or not

1
2
3
4
5

POST /api/v1/users/check_sms_token

{
  "sms_confirmation_token": "abcd"
}

if the token is correct, he calls the Recover Password to update his password

if the token is correct, the response is as following,

1
2
3
4
5
6

{
  "msisdn": "84932466",
  "username": "Mike Jackson",
  "authentication_token": "h-jkDAMwJzrsm-4bvgzw",
  "valid_for_authentication": true
}

If the SMS confirmation token is invalid

1
2
3
4
5
6
7
8

{
  "error": "Invalid resource. Please fix errors and try again.",
  "errors": {
    "sms_confirmation_token": [
      "is invalid"
    ]
}
}

If the SMS confirmation token is expired

1
2
3
4
5
6
7
8

{
  "error": "Invalid resource. Please fix errors and try again.",
  "errors": {
    "sms_confirmation_token": [
      "is expired"
    ]
}
}

Recover password

After the user receives the SMS, he should enter the verification code and new password

1
2
3
4
5
6

POST /api/v1/users/change_password_by_sms

{
  "sms_confirmation_token": "abcd",
  "password": "12345678"
}

If the update is successful, it returns the user information same as above.

Reset password

The user can reset his password by this API.

PUT /api/v1/users/change_password

This API needs authentication

Expected parameters in the body
- current_password: the current password
- password: new password

1
2
3
4
5
6

POST /api/v1/users/change_password

{
  "current_password": "12345678"
  "password": "87654321"
}

if the change is successful, the server return response like

1
2
3
4
5
6

{
  "msisdn": "84932466",
  "username": "Mike Jackson",
  "authentication_token": "h-jkDAMwJzrsm-4bvgzw",
  "valid_for_authentication": true
}

After the user updates his password, the authentication_token will be regenerated. So the user need to login again.

Facebook signup

When the user authenticate with facebook, the client will authenticate with Facebook client and send a facebook token
to the server like following,

1
2
3
4
5

POST /api/v1/fb_login

{
  "access_token": "12sdfs23423suworjowjerowruouro3rwoefijwoefjwe"
}

After the server receives the token, it will get the user information from facebook, and then returns the client following
information as response

1
2
3
4
5
6
7

{
  "username": "Mike Jackson",
  "gender": 'male',
  "birthday": '1984-03-20',
  "msisdn": "84932466",
  "email": "[email protected]"
}

The facebook doesn’t need to signup, if after it logins, it will be created in Xhoppe database automatically.