1.1. Overview:

The UDSM Real Time API allows for simple, efficient, cross-system calls for pushing user data between the Magnet Platform and its clients.

1.2. Architecture:

There are 2 types of calls:
a. Upstream (OM -> Client)
b. Downstream (Client -> OM)
In each call the side originating the user update request will use an HTTPS POST to a listener on the other side's system. The receiving side wil then accept the request, validate it, parse the data, and then synchronized its internal database/s accordingly.
OM's listener will reside on: https://[secure_prefix]/[master_node]/enterprise_real_time.php

1.3. Synch Logic:
Each record has a field called aux_id. This is the common key for both systems. It is unique to each user and must be an integer. Each request should have a last_update_date variable in it which will let the other side know how recent the update is. The receiving side use the aux_id to locate the record, and the last_update_date to determine whether or not to apply the newly received data to it.

2.1. Requests: Upstream (OM -> Client)
Every time a user updates his/her info the following HTTPS POST is pushed to the Client's Real Time Listener (RTL):

Var Name: source
Sample Value: 'OM - xyz.org'
Format: string.
Description: The domain where the update took place.
Value Set: n/a.
Required: yes.
Comments: Client may want to validate this.

Var Name: type
Sample Value: 'myaccount'
Format: string.
Description: What type of update this is.
Value Set: myaccount|checkout|admin
Required: yes.
Comments: n/a.

Var Name: token
Sample Value: n/a.
Format: string.
Description: Agreed upon token used to authenticate the request.
Value Set: n/a.
Required: yes.
Comments: n/a.

Var Name: update_id
Sample Value: n/a.
Format: integer.
Description: OM-generated update serial number.
Value Set: n/a.
Required: yes.
Comments: Mainly for reference. Never resets.

Var Name: user_ip
Sample Value: '1.1.1.1'
Format: string.
Description: The IP address the user updated from.
Value Set: n/a.
Required: yes.
Comments: For reference.

Var Name: user_data
Sample Value: n/a.
Format: array.
Description: The actual data.
Value Set: n/a.
Required: yes.
Comments:
1. Type 'myaccount' of 'admin' the user_data assoc. array will contain ALL fields. Empty fields are considered to have no value.
2. Type 'checkout' will only contain the fields below, the rest should be left untouched.
- aux_id
- email
- first_name
- last_name
- work_company*
- home_addr_1**
- home_addr_2**
- home_addr_city**
- home_addr_state**
- home_addr_state_other**
- home_addr_zip**
- home_addr_country**
- home_tel**
* only if user labels this as a work address
** home_ or work_ - depends on user choice.

Var Name: source
Sample Value: 'HBS - Advance'
Format: string.
Description: The source where the update came from.
Value Set: n/a.
Required: yes.
Comments: n/a.

Var Name: token
Sample Value: n/a.
Format: string.
Description: Agreed upon token used to authenticate the request.
Value Set: n/a.
Required: yes.
Comments: n/a.

Var Name: update_id
Sample Value: n/a.
Format: integer.
Description: Client-generated update serial number.
Value Set: n/a.
Required: yes.
Comments: Mainly for reference. Never resets.

Var Name: update_date
Sample Value: '1326217835'
Format: integer.
Description: The UNIX TIMESTAMP for when the actual update took place.
Value Set: n/a.
Required: yes.
Comments: For reference.

Var Name: node_distribution_string
Sample Value: 'xyz.org,abc.org'
Format: string.
Description: The domains this user should be injected into.
Value Set: n/a.
Required: no.
Comments: This is only used to ADD a user to a Node.

Var Name: user_data
Sample Value: n/a.
Format: array.
Description: The actual data.
Value Set: n/a.
Required: yes.
Comments:
Required fields:
- aux_id
- email
- first_name
- last_name
Note: sending an empty field for email, first_name, or last_name will clear those fields for this record on the OM database.  All other fields are optional and should not be passed if there is no change (they will not be cleared if not passed or passed empty). If you want to force-clear any of them, use a '[C]' directive if a field should be cleared. Fields-names not found in the Client's MUUT will generated an error.

3.1. Replies:
Replies will be small text snippets in the following format:

3.2.a. OM Reply to Client (success):
---
01. Status: 100-success
02. ##### Synch yourmasternode.org #####
03. Added 158(16302) to yourmasternode.org
04. Updated users table for 158(16302) on yourmasternode.org
05. Updated profiles table for 158(16302) on yourmasternode.org
06.
07. ##### Synch yourfirstnode.org #####
08. Synch Ok. No need to update, user skipped.
09.
10. ##### Synch yoursecondnode.org #####
11. Synch Ok. No need to update, user skipped.
---

3.2.b. Reply explained:
Status: 100-success -- self explanatory. Here for ease of parsing.

##### Synch [node] ##### -- Indicates which nodes the request traversed through.

Added 158(16302) to [node] -- UID 158, aux_id 16302 was added to the node (UDSM Registration). Thi will only appear when the user is added eitehr by default to the Master Node or via node_distribution_string directive. The last part is the Node (redundant but is there for parsing purposes should the client need it).

Updated users table for 158(16302) on [node] -- Indicates that the users table was updated for this uid(aux_id).
Updated profiles table for 158(16302) on [node] -- Indicates that the profiles table was updated for this uid(aux_id).
Note: A record on the Master Node may also be skipped due to higher last_update_date value. This can be seen as the script traverses

3.2.a. OM Reply to Client (error):
(One of the following below:)
---
Status: 101 - Error-unauthorized ip
Status: 102 - Error-bad token
Status: 103 - Error-bad request
Status: 104 - Error-data processing
Status: 105 - Record too old.  update_date should be a maximum of X days old. (X is configurable).
---

3.2.b. Reply explained:

3.4. Client Reply to OM:
---
Status: 100
aux_id: 12345
Elapsed: .6234 sec
---

3.5. Reply explained:
Status: 100-success; 101: Error-unauthorized ip; 102: Error-bad token; 103: Error-bad request; 104: Error-data processing
aux_id: the record's aux_id
Elapsed: Time elapsed from when the request was received to when it was completed.