Re: [Agendaware-dev-server] XML APIs
Status: Inactive
Brought to you by:
zacklink
Menu
▾
▴
Re: [Agendaware-dev-server] XML APIs
|
From: zack <za...@th...> - 2001-11-11 04:11:06
|
Good stuff Shane. I bet anyone who is subscribed to both server and client mailing lists is starting to get tired of getting 2 copies of every email, but, it should only be this way in the beginning, as we are hashing out the comms side. Once we get our protocol down, there should rarely be any duplicates. Comments on the doc below... ZL > > > ------------------------------------------------------------------------ > > Below are listed the client server communication XML API's. > Listed below are explanations of elements as well as sample > communication that would be involved. The root element of all > communication is <Agenda></Agenda> > > 1. Init > > Init is used to initialize communications between the server > and potential client. This method may be used to set certain > communication settings before starting logon (such as whether to > use SSL). The example below shows how to init a connection > with SSL turned off. If settings are specified, the settings > (such as ssl) should be started on the next client request. > > Client: > <Agenda> > <InitConnectionSubmit ssl="0"/> -- don't use ssl > </Agenda> > Server: > <Agenda> > <StatusMessage success="1"/>Initialization successful</StatusMessage> -- init successful > </Agenda> How about using a non-ssl port and an ssl port? From the client side, if I send a msg saying the next client request will be ssl, I have to build a whole new connection to the server with ssl handshake etc. Also, I don't know how it is in c++, but I don't think you could bind a server socket, and an ssl server socket to the same port. Init can still be used for any other settings we might want to pass. The only other thing I can think of off the top of my head would be if we were using some load balancing system, where a server redirects clients to a less busy server or something. But other things could come up that we could tuck in here. > > > 1. Login/Logoff > > The following request will login a user into the system > after the "Init" request has successfully processed. > > Client: > <Agenda> > <Login username="jackl", password="jackrabbit"/> > </Agenda> > Server: > <Agenda> > <StatusMessage success="1">jackl logged in</StatusMessage> -- successful login > </Agenda> > > OR. . . > <Agenda> > <StatusMessage success="0>Invalid user: jackl</StatusMessage> > </Agenda> > > Client: > <Agenda> > <Logoff/> > </Agenda> > Server: > <Agenda> > <StatusMessage success="1">jack1 logged off from ??</StatusMessage> > </Agenda> > > > 2. Email APIs > > A. Request an email by id (each email will have a uniqueId) > and only return header information (format="header"). > If you want complete email, user format="complete". > This will return all information for the message (sender, cc, bcc, > attachment, body, etc. . ) This is a good idea. Will provide some flexibility on the client side to deal with things like slow links or user preference or whatever. > > Client: > <Agenda> > <RetreiveMailMessageRequest format="header"> > <Uid>dkkfjslwiefoweif22320239</Uid> -- 1 or more Uids > </RetrieveMailMessageRequest> > </Agenda> > Server: > <Agenda> > <MailMessageReply> > <MailMessage> -- 1 or more messages > ............. > </MailMessage> > </MailMessageReply> > </Agenda> > > B. Request any new (complete) messages since July 3, 2001 @ 2:00 pm From the client point of view, it would be easier to deal with seconds from Jan 1, 1970 (epoch), as that is how Java measures time. Other formats, like the one below, is fine if it's easier that way on the server, but epoch time saves me a line or 2 of code every time I use it. Which also brings up the point, that I think the server should send a time stamp (preferably seconds since epoch) to the client when the client requests all messages. What this does is gives us an easy way to retrieve msgs since a certain time, that won't be screwed up by workstations with their clocks off, or clients that switch timezones. > > Client: > <Agenda> > <RetrieveMailMessageRequest format="complete"> > <LastCheckTime value="200107031400"/> > </RetrieveMailMessageRequest> > </Agenda> > Server: > <Agenda> > <MailMessageReply> > <MailMessage> -- 0-n mail messages > ............ > </MailMessage> > <MailMessage> > ............. > </MailMessage> > </MailMessageReply> > <Agenda> > > We may be able to use a timestamp such as "0" > to indicate that we want all messages. > > > C. Send a new message > > Client: > <Agenda> > <NewMailMessageRequest> > <MailMessage> -- 1-n mail messages > ............ > </MailMessage> > </NewMailMessageRequest> > </Agenda> > Server: > <Agenda> > <StatusMessage success="1">Message sent successfully</StatusMessage> > </Agenda> > > > D. Delete a message given 1 or more unique ids > > Client: > <Agenda> > <DeleteMailMessageRequest> > <Uid>kdjflslfksj</Uid> -- one or more uids > </DeleteMailMessageRequest> > </Agenda> > Server: > <Agenda> > <StatusMessage success="1">Message ??? deleted</StatusMessage> > </Agenda> > > > E. Update a message. This may include changing the "view" it's associated with > and other things like that. The original message itself won't change, just a few attributes > that are associated with it for sorting, searching, folder location, etc. . . > > Client: > <Agenda> > <UpdateMailMessageRequest> > <MailMessageUpdate> -- 1 or more mail message update > <Uid>kdsjf</Uid> > <Attributes>laksdjf;lsdkjf</Attributes> > </MailMessageUpdate> > </UpdateMailMessageRequest> > </Agenda> > Server: > <Agenda> > <StatusMessage success="1">Messages updated</StatusMessage> > </Agenda> > > 2. Directory APIs > > A. Request a directory entry based on uid (summary or complete). > > The format parameter can be "summary" or "complete". This is similar > to the email API where you can receive just header information > or the entire message, the same goes for directory entries. > Client: > <Agenda> > <RetrieveDirectoryRequest format="summary"> > <Uid>kdkdkdkd</Uid> -- 1 or more uids > </RetrieveDirectoryRequest> > </Agenda> > Server: > <Agenda> > <DirectoryEntryReply> > <DirectoryEntry> -- 0 or more replies > .............. > </DirectoryEntry> > </DirecotryEntryReply> > </Agenda> > > B. Request a directory entry or entries based on search parameters. > > Client: > <Agenda> > <RetrieveDirectoryRequest format="summary"> > <DirectorySearch> > <SearchParms> -- 1 or more search parameters > </SearchParms> > <DirectorySearch> > </RetrieveDirectoryRequest> > </Agenda> > Server: > <Agenda> > <DirectoryEntryReply> > <DirectoryEntry> -- 0 or more replies > .............. > </DirectoryEntry> > </DirecotryEntryReply> > </Agenda> > > C. Update a directory entry (pending appropriate permissions) > > Client: > <Agenda> > <UpdateDirectoryRequest> > <DirectoryEntry> -- 1 or more entries > </DirectoryEntry> > </UpdateDirectoryRequest> > </Agenda> > Server: > <Agenda> > <StatusMessage success="1">Entries updated</StatusMessage> > </Agenda> > > D. Delete a directory entry (pending appropriate permissions) > > Client: > <Agenda> > <DeleteDirectoryRequest> > <Uid>kksksks</Uid> -- 1 or more uids > </DeleteDirectoryRequest> > </Agenda> > Server: > <Agenda> > <StatusMessage success="1">Entry deleted</StatusMessage> > </Agenda> > > > 3. Administration APIs > > All APIs below are performed assuming an appropriate administrator has logged in. Up to now, I had assumed we would do a server based admin tool. But I like this. I will add an admin gui to the client side. On the server we can just provide some command line tool(s) to do the same stuff. > > A. Add a user to the system (this implies adding to the directory also) > > Client: > <Agenda> > <AdminRequest> > <UserAdd> > <User> 1 or more users > </User> > </UserAdd> > </AdminRequest> > </Agenda> > Server: > <Agenda> > <StatusMessage success="1">Users added</StatusMessage> > </Agenda> > > B. Edit a user in the system. > > Client: > <Agenda> > <AdminRequest> > <UserEdit> > <User> -- 1 or more users > </User> > </UserEdit> > </AdminRequest> > </Agenda> > Server: > <Agenda> > <StatusMessage success="1">Users edited</StatusMessage> > </Agenda> > > C. Delete user from the system. > > Client: > <Agenda> > <AdminRequest> > <UserDelete> > <Uid></Uid> -- 1 or more uids > </UserDelete> > </AdminRequest> > </Agenda> > Server: > <Agenda> > <StatusMessage success="1">Users deleted</StatusMessage> > </Agenda> > > D. Query if user is logged on. > > Client: > <Agenda> > <AdminRequest> > <UserLoggedIn> > <Username></Username> -- 1 or more uids > </UserLoggedIn> > </AdminRequest> > </Agenda> > Server: > <Agenda> > <StatusMessage success="1">Users ?? logged in</StatusMessage> > </Agenda> > > E. Query connection statistics for user if logged in. > > Client: > <Agenda> > <AdminRequest> > <RetrieveConnectionStats> > <Uid></Uid> -- 1 or more usernames > </RetrieveConnectionStats> > </AdminRequest> > </Agenda> > Server: > <Agenda> > <ConnectionStats> > </ConnectionStats> > </Agenda> > > F. Drop user's connection. > > Client: > <Agenda> > <AdminRequest> > <DropConnection> > <ConnectionId></ConnectionId> -- 1 or connections > </DropConnection> > </AdminRequest> > </Agenda> > Server: > <Agenda> > <StatusMessage success="1">Connections dropped</StatusMessage> > </Agenda> > > G. Set system parameters not available in config files? > > Client: > <Agenda> > <AdminRequest> > <SetSystemParameter> > <Parameter></Parameter> -- 1 or more params > </SetSystemParameter> > </AdminRequest> > </Agenda> > Server: > <Agenda> > <StatusMessage success="1">Parameters set</StatusMessage> > </Agenda> > > H. Get a system parameter > > Client: > <Agenda> > <AdminRequest> > <GetSystemParameter> > <ParameterName></ParameterName> -- 1 or more parameters > </GetSystemParameter> > </AdminRequest> > </Agenda> > Server: > <Agenda> > <Parameter> -- 1 or more parameters > </Parameter> > </Agenda> > > I. Tell system to re-read config files? > > Client: > <Agenda> > <AdminRequest> > <RereadConfig/> > </AdminRequest> > </Agenda> > Server: > <Agenda> > <StatusMessage success="1">Configuration reread</StatusMessage> > </Agenda> > > J. Tell system to clean cached information? > > Client: > <Agenda> > <AdminRequest> > <PurgeCache/> > </AdminRequest> > </Agenda> > Server: > <Agenda> > <StatusMessage success="1">Cache purged</StatusMessage> > </Agenda> > > > |
