BookmarkSync Client/Server Communication

This is an evolving document concerning the client/server communication between BookmarkSync: what the client sends to the server, what they expect in return, and so on and so forth. This document is not official - it has arisen solely from the 0.1 minimal PHP server code recently uploaded to Sourceforge. Developers can use the information within to create their own client or server code. Again, this is not official.

This is a work-in-progress. Email morbus@disobey.com concerning modifications, thoughts, etc.

The Initial Handshake
The Body of a Message
Waving Good-bye
Syntax Reference
Version History

The Initial Handshake

The client initiates all requests with a normal HTTP POST containing six variables (case-sensitive):

Variable Name	Variable Explanation
Email	The Email of the client's user. User must be pre-registered with the server.
md5	An MD5 hash of the client's user password. User must be pre-registered with the server.
Token	An incrementing value that represents the last set of data downloaded from the server.
Contents	A list of commands for the server to process (see The Body of a Message).
CharSet	Optional. The client's local character set, as determined by the operating system.
Version	Optional. The client's version information (need more info - what format can it take?)

Once the server has received this information, it will validate the user based off the Email and md5 of the user's password. If authentication is a success, the server returns a "Hello" in the form of (note that all responses to and from the server are terminated with a \r\n - I'll continue to show them below for safety's sake):

*S,Root,\"http://www.servernamehere.com/\"\r\n"

If authentication failed, the server returns one of the following errors (note that the final part of any response should always be *Z, presumably a mnemonic for Ctrl-Z. As before, I'll continue to show them):

# if the user's email address could not be found,
# *N is returned, presumably for "N"ot Found.
*N\r\n*Z\r\n

# if the user's password failed, *P is returned,
# presumably to indicate a "P"assword failure.
*P\r\n*Z\r\n

Once the server has authenticated the user, it will compare the client's Token with the latest token value of the server. If the server value is greater, the server will send back the value of the newest token (*T), the "begin data" syntax (*B), and then a list of all the stored bookmarks:

# the server's token is newer than the client's
# token, so send the token itself, and then the
# "begin data" marker:
*T,SERVERTOKENVALUE\r\n*B\r\n

# the server will then send line after line of
# path/url pairs, like the below sample (the escaped
# quotes are intentional and must be sent):
\"PATH1\",\"URL1\"\r\n
\"PATH2\",\"URL2\"\r\n
\"PATH3\",\"URL3\"\r\n
\"PATH4\",\"URL4\"\r\n
\"PATH5\",\"URL5\"\r\n

Once the server has sent the list of bookmarks, it will end the communication with *Z. If the client bookmarks do not need to be updated, then we'll enter into the The Body of the Message, which contains all the client commands to add or delete bookmarks and directories on the server.

The Body of the Message

If the server has successfully authenticated the user and the tokens have been checked to ensure there's nothing new for the client to download, the server will look through the Contents of a client's POST in hopes of finding A ("add bookmark"), D ("delete bookmark"), M ("make directory"), or R ("remove directory") commands:

# in this example, we're Adding a record named "\Microsoft Windows
# Update" - note that the path of the bookmark is combined with 
# it's title (in this case, "\" refers to the root location of the
# bookmark hierarchy, and "Microsoft Windows Update" refers to the
# bookmarks title), with a URL of blah, blah, blah. The escaped
# quotes are necessary, and your server code should expect them.
A,\"\\Windows Update\",\"http://v4.windowsupdate.microsoft.com/en/default.asp\"\r\n

# here, we're creating a directory called "testing".
# the three slashes at the end really represent an
# escaped \ and an escaped ". they're necessary.
M,\"\\testing\\\"\r\n

# and now, add a new bookmark into our newly created directory.
# each directory hierachy is represented by the two slashes.
A,\"\\testing\\Disobey.com\",\"http://disobey.com/\"\r\n

# alright, now delete the bookmark we just added.
D,\"\\testing\\Disobey.com\",\"http://disobey.com/\"\r\n

# and the "testing" directory too.
R,\"\\testing\\\"\r\n

Once the server has finished processing the commands in Contents, it will generate and send a new token (*T, which the client should store for future use during The Initial Handshake) and then the standard *Z. If the server receives a command besides A, D, M, or R, it'll send back *E to indicate that an error has occured; surprisingly, no *Z is included (note: I've asked the developer's about this).

Waving Good-bye

All server responses should end with *Z.

Syntax Reference

Syntax Example	Syntax Explanation
*N	The user's `Email` could not be found.
*P	The user's `md5` of their password was invalid.
S,Root,\"http://www.servernamehere.com*/\"	The server is ready to process additional commands.
T,SERVERTOKENVALUE*	The latest token (representing the latest set of bookmarks) from the server.
*B	Instructs the client that the server is sending the complete list of bookmarks.
*Z	Indicates that commnication with the server is over.
\"PATH\",\"URL\"	A list of bookmarks from the server, for the client to process.
A,\"PATH\",URL\"	Instructs the server to add a new bookmark.
D,\"PATH\",URL\"	Instructs the server to delete an existing bookmark.
M,\"PATH\"	Instructs the server to add a new directory.
R,\"PATH\"	Instructs the server to remove an existing directory.

Version History

2003-10-01: First draft posted.