Sample API Code

The server returns Client ID (GUID) which the client will use in any following calls to the server.

Uses required keys (ProtoVer, ClientID, Identifier, AuthMethod, Password, Client, OS, Platform). Notice that server returns a Uhid of "969" for the devtest@plaxo.com account. We can use this in follow-on commands for authentication instead of keys Identifier and AuthMethod. The server returns 200 to show that the command completed successfully.

The server returns folders Contacts, Calendar, Tasks, Notes. Client uses Uhid to log in. Notice server doesn't return the Uhid in this case. Best practice is to use the Uhid once you have it from the first authentication with the server.

Shows data fields the server supports. Note the fields are in alphabetical order. The client immediately follows this with a Map command for the item the server asks to add.

The Map command for the returned server add for the entry "Dev Friend". The client must update its anchors (LastAnchor and NextAnchor) after the server returns success for the map command.

Initial Slow Sync from a client having one contact "Hunter Green" with a personal email address. Server has one entry, "Dev Friend". Client must send up all the fields that it supports. As before, server sends the one item it has in its database that the client doesn't have a match for, "Dev Friend".

The Map command for the returned server add for the entry "Dev Friend". The client must update its anchors (LastAnchor and NextAnchor) after the server returns success for the map command.

Ping. Shouldn't be any updates since we just successfully synced and mapped. Ping is done over http, so must not use authentication. Just use the Uhid, no Password.

To demonstrate what happens when a user makes a change to their server address book, I use Plaxo Online on testapi to add a contact to my devtest account address book, http://testapi.plaxo.com. I add a contact named "Third Contact". Now when the client pings the server, it should report that there has been a change. Ping again. Ping is done over http, so must not use authentication. Just use the Uhid, no Password. This time, the server should say that the client needs to sync by returning 205.

Fast Sync. Since the client-server relationship has been established, subsequent sync commands only need to include the changes since the last sync. This is called a fast sync. Client does not have updates since the last sync, but the server responded to the previous ping that a sync is required. Notice the client has updated anchors in this example. As before, server sends the one item it has in its database that the client doesn't have a match for, "Third Contact".

The map command for the returned server add for the entry "Third Contact". The client must update its anchors (LastAnchor and NextAnchor) after the server returns success for the map command.

Subsequent Fast Sync with client editing "Hunter Green" contact changing last name to O'Ryan (to show handling of the '). Notice the client has updated anchors in this example and is sending up all of its supported fields.

Subsequent Fast Sync with client deleting "Third Contact" contact. Notice the client does not need to send data in this case. Notice the sync anchors have been incremented. (If you have mapped the wrong ServerID number, the server won't tell you when you later try to access it through your local ID.) Notice that the client doesn't need to remember the server ID for the item. The client uses its ItemID to delete "Third Contact."

Subsequent Fast Sync with client forgetting to update the anchors. Notice that the server returns a status code of 412 to tell the client to slow sync.

Slow Sync with client re-sending all of its data (2 contacts, "Dev Friend" and "Hunter O'Ryan")

This example relies on having executed Example 8 first so you can see the changes to the contacts in the account on Plaxo Online. Slow Sync with full merge: 2 contacts, "Dev Friend" and "Hunter O'Ryan". Hunter has a company name. Dev Friend has some more address info. The server takes care of merging the data and reports the result of the merge to the client in the response.

First, using the Manage Folders link on Plaxo Online, I create a new contacts folder in the devtest account called Personal. Then I use Get to get the list of folders and their folder IDs.

Now I add a contact, Hunter Green, to the Personal folder, using Target of 'Contacts/2995' to indicate that I am updating contacts in FolderID 2995 (which was returned in the Get command).

Starting with an empty address book, client adds 2 contacts: Hunter Green and Seth Travers.

Client now modifies Hunter Green to Hunter Grên, and deletes Seth Travers—remembering to update anchors.