blog documentation followers forum marketplace

The Proxima User Service

Proxima » Documentation » Using Proxima » The Proxima User Service

Table of Contents:


What is the Proxima User Service?
(POST) - Create a new User Account
(POST) - Log in an existing User Account
(PUT) - Update an existing User Account
(PUT) - log out and end a user session
(GET) - Get stored data for an existing User Account
(DELETE) - Delete an existing User Account

  • What is the Proxima User Service?

    The Proxima User Service is an API Service that let's you do the following:

    - Create User Accounts
    - Update User Accounts (i.e. add or remove key value pairs to existing user data)
    - Get stored key/value pairs for an existing User Account
    - Delete User Accounts
    - Log Users in to your app so they get an "active client session"

  • (POST) - Create a new User Account

    Creating a new User Account is easy - send a POST request to the api/user service with the following key/value pairs:

    - user_name (optional) a user name for the new user account
    - user_email (optional) a unique email address for the new user account
    - password (required) a password for the new user account

    Note that you can configure which of the additional fields are required in your Proxima User Global Config from the Jamroom ACP.

    So to create a new user account where we have not required a "user_name" or "user_email" would look like:

    POST http://yoursite.com/api/user?password=abc123

    All we need to pass to the service is a password - if everything goes as planned, you will receive a 201 HTTP Status Code with a note of "user created and session started".
    The response will be a JSON response and look similar to:

    {
  code: 201,
  text: 'Created',
  note: 'user created and session started',
  data: 
  { 
    _id: 1245,
    session_id: '85983d0cebbf85699081cb3c805a2995',
    location: 'http://yoursite.com/api/user/1245'
  }
}

    Things to note:

    - all Proxima responses will have (at minimum) a code and text field - in this case a code of "201" means the new user account was "Created".

    - there is a "data" object in the response that includes the unique "_id" field - this is the unique user id that was created for this new user account, and should be stored for use on future logins.

    - the "session_id" is a unique session identifier that means the user has successfully been logged in to the system. You must save this value in your client and include it on all future requests as the "password" portion of the HTTP Basic Authentication header.

    - the "location" value is the unique URL for actions pertaining to this unique user account (i.e. to retrieve information about, request a password reset, delete the account, etc.)

  • (POST) - Log in an existing User Account

    If a user session has expired (sessions expire 7 days after they are created), then to gain access to the system again a POST request must be sent to the user login endpoint, along with the unique "id" and "password" for the user:

    POST http://yoursite.com/api/user/login?id=1245&password=abc123

    If successful, a new session will be established for the user account, and a new session_id generated and returned:

    {
  code: 200,
  text: 'OK',
  data:
  {
    session_id: '85983d0cebbf85699081cb3c805a2995'
  }
}

    Make sure and store that unique session_id and use it as the "password" value in your HTTP Basic Authentication header going forward.


  • Any additional key/value data pairs sent in the POST request will be stored to the created User Account

  • (PUT) - Update an existing User Account

    Once a User Account has been created, and the user has established an active User Session (either by having just created the user account, or by logging in), you can store additional key/value pairs as part of the user account by sending a PUT request to the user account's unique User URL:

    http://yoursite.com/api/user/1245

    In this case "1245" is our unique user_id, so our PUT request would be sent to that URL.

    You can include any number of key value pairs you would like to store as part of the user's account information - i.e.

    PUT http://yoursite.com/api/user/1245?first_name=Brian

    Would update user_id 1245 and create (or update) a new Key called "first_name" with value "Brian". When you make a GET request now to the unique User URL, there will be a new "first_name" key in the data set.

    You can create, update and delete keys all in the same call - i.e.

    PUT http://yoursite.com/api/user/1245?first_name=Brian&middle_name=__delete_key

    would change the "first_name" value to "Brian" and DELETE the "middle_name" key completely. Note the special "__delete_key" value that is used to tell Proxima the key should be removed.
  • Proxima will accept key value pairs passed on the URL (i.e. "GET" style) as well as form encoded (i.e. in the body) - most quality REST client libraries will handle this for you.

  • (PUT) - log out and end a user session

    You can log out and end an existing User Session by sending a PUT request to the "logout" API endpoint:

    http://yoursite.com/api/user/logout

    This will end the existing User Session. In order to interact with Proxima endpoints a new session will need to be established.

  • (GET) - Get stored data for an existing User Account

    Once a User Account has an active session, you can send a GET request to the unique User URL to retrieve the stored information about that user account:

    GET http://yoursite.com/api/user/1245

    If the user account exists, you will receive a 200 response ("OK") with a data set containing the user's stored information - i.e.:

    {
  code: 200,
  text: 'OK',
  data:
  {
    _created: 1411149399,
    _updated: 1411149399,
    first_name: 'Brian'
  }
}

    All Objects stored in Proxima have:

    - a Unique ID called "_id"
    - a "created time" returned as "_created"
    - a last updated time returned as "_updated"

    The _created and _updated time are in GMT Epoch time, and the _id is numerically ascending.
  • Keys in Proxima that start with an underscore (_) are "internal" keys that are maintained by the system (just like in Jamroom) - all keys that start with an underscore are reserved - sending a new key that begins with an underscore in a POST or PUT request will result in a 400 error.

  • (DELETE) - Delete an existing User Account

    A User can delete their user account by sending a DELETE request to their unique User URL:

    DELETE http://yoursite.com/api/user/1245

    Note that the user MUST have an active User Session, and they can only delete their own account.

    If successful, a "200" OK response will be returned indicating the user account was successfully deleted:

    {
  code: 200,
  text: 'OK'
}

    The user's session will no longer be valid, and a new account will need to be created before they can access the system again.

Tags