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 concerning modifications, thoughts, etc.

Table Of Contents

  1. The Initial Handshake
  2. The Body of a Message
  3. Waving Good-bye
  4. Syntax Reference
  5. Version History

The Initial Handshake

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

Variable NameVariable Explanation
EmailThe Email of the client's user. User must be pre-registered with the server.
md5An MD5 hash of the client's user password. User must be pre-registered with the server.
TokenAn incrementing value that represents the last set of data downloaded from the server.
ContentsA list of commands for the server to process (see The Body of a Message).
CharSetOptional. The client's local character set, as determined by the operating system.
VersionOptional. 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):


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.

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

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:

# 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):

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\",\"\"\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.

# and now, add a new bookmark into our newly created directory.
# each directory hierachy is represented by the two slashes.

# alright, now delete the bookmark we just added.

# and the "testing" directory too.

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 ExampleSyntax Explanation
*NThe user's Email could not be found.
*PThe user's md5 of their password was invalid.
*S,Root,\"\"The server is ready to process additional commands.
*T,SERVERTOKENVALUEThe latest token (representing the latest set of bookmarks) from the server.
*BInstructs the client that the server is sending the complete list of bookmarks.
*ZIndicates 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

Morbus Iff (aka Kevin Hemenway), 2003-10