Afteroffice.com

Afteroffice Server API (version 2.0a)
RFC draft 2
This paper provides information for developer to write add-on solution on top or within of Afteroffice Server (AOS) environment.
The API is currently implemented on HTTP method, via TCP/IP.
The Developer Add-on (DA) may query AOS with simple HTTP get/post query, thru a pre-defined commands set to the AOS host.
In version 1.0 of AOS API, the AOS host must be configured to “listen” to a specific DA or else queries for non-authorised DA will be ignored.
All commands based on version 1.0 API are compatible in 2.0, and behaved the same.
Version 2.0 API however do not require DA to register with AOS. The DA may query the server the same way as the browser does, as long as the authentication is true. DA in this case, is more like the browser, acting like a user. AOS will treat DA login as a regular user, but provide more option on generating the result back to DA.
Flow of the communicationPassing SID to DAQuery the AOSAOS commandsUser specification tableAOS config table Flow of the communication
User/DA authenticate with the AOS, and obtain a session id (refer as SID).
SID has the following format:SIDxxxxxxxxxxxxxxxxxxWhere “SID” is the prefix of the string, and irregular pattern text of the rest of the string. Length of the SID may be 19 to 21 characters.
Eg:SID78889x23736345h80SID54545k22545235i54 SID will then be used as a reference to the active user/DA. It is like Cookie for browser, just that SID concept was developed and works well on browser that incapable or diabled on Cookie support.
SID passes back to the main server on each query, embedded in the URL. The server proceed with the SID only if the session is still active.
SID will be dismissed in the following ways:- the user/DA logout.
- the user/DA has not query to the server for a predefined time.
- the admin drop the user/DA session SID is always unique, user/DA will never get the same SID no matter how many times they login.
Passing SID to DA
Developer Add-on (DA) receive SID in 3 ways:-
1. a query from user browser, where redirect from AOS
2. the DA initiate the login query
3. a query directly from AOS (call back)
If DA is not responsible for initiating the session, it may then proceed to verify the SID by passing it back to AOS, or may just ignore it if the SID was not authorised.
It is the DA responsibility to validate the SID. In most cases, DA should keep a list of SID for faster handling on user requests, avoiding to pass back verification query to the AOS.
However, if the DA is not responsible for initiate the session, the first SID arrive to DA must be verified before proceed.
Some DA handle user browser request directly. In order for AOS to redirect SID to a DA, AOS must know the entry point of the DA, in this case, is the DA’s URL.
DA URL may looks something as such:-http://daserver.dadomain.com/dascript.pl?sid=SIDxxxxxxxxxxhttp://192.168.1.5/da.cgi?sid=SIDxxxxxxxxxx AOS instructs the user browser to query DA with the predefined DA URL, by specifying the user SID as URL parameter.
The developer responsible for a DA must let the AOS admin know the Entry Point of the DA (which is only an URL) so that AOS may redirect the user correctly.
Query the AOS
Once DA received a SID feed from user browser, the SID can be easily extracted from the field=data set of the URL.
SID is specify in the URL as:-sid=SIDxxxxxxxxxxxxx A typical conversation between AOS and DA may looks like this: DA query user data from AOS with the following HTTP request:-http://www.afteroffice.com/sqSpec.user.mms?sid=SIDxxxxxxxxxxxxxWhere: “www.afteroffice.com” is the AOS host, “sqSpec” (case insensitive) is the CGI command, “user” is the AOS object, “mms” is the CGI suffix.
AOS returns the user profile if the SID is valid. Note API v1.0: A DA must obtain permission from AOS admin before sending any query to AOS. The AOS verify each query from DA by checking the registered DA host IP.
AOS commands
Command sqOpen
Syntax:
http://www.afteroffice.com/sqopen.user.mms?da=DAName
Parameters: da: The name of the DA. AOS will look up the DA
database for this name, compare the IP from the host making the
query from.
Use: DA send this command to AOS to notify that the DA host is
available to handle user query. It is an authentication process for
AOS to recognise the DA as well.
Return: “true” if the DAName is recognise and the IP verification
correct. “false” if either one not regconise.
See also: sqClose,sqIdle
Command sqClose
Syntax: http://www.afteroffice.com/sqclose.user.mms
Parameters: none
Use: Tells the AOS to stop directing user query to DA. Use before
DA host performing a restart or some major upgrade.
Return: “true” if the sqOpen was successful, “false” if the
connection between DA and AOS has never established.
See also: sqClose,sqOpen
Command sqIdle
Syntax: http://www.afteroffice.com/sqIdle.user.mms
Parameters: none
Use: Tell the AOS that the DA is on idle. It it necessary to invoke
this query on the following situation:-
- the DA has been idle, not sending any query to AOS for more
than an hour.
- the DA is AOS call-back compatible, and ready to process the
AOS non-critical instructions (garbage collection or other tasks).
Note that AOS has a habit to “forget” the availability of DA after 2
hours (120 minutes) of inactivity (the DA fail to query the AOS with
any command in 2 hours). sqClose will be invoked by AOS after DA
time-out. The DA will have to initiate sqOpen again if AOS closes
the DA. It is a good practice to send sqIdle to AOS every hour to
ensure the connectivity. However, DA should not send the sqIdle
query to AOS if there is enough traffic to keep the AOS
acknowledge that the DA is alive.
Return: “true” if the sqOpen was successful, “false” if the
connection between DA and AOS has never established.
See also: sqClose,sqOpen
Command sqSpec
Syntax:
http://www.afteroffice.com/sqSpec.user.mms?sid=SIDxxxxxxxx&fl
d=name,fullname,host&format=url
Parameters:
sid: The SID of the active user.
fld (optional): The fields list that DA would like to obtain data from.
It is a comma separated field name list. Omitting this parameter
get a standard data set.
format (optional): Return data format, see Return.
Use: This command fetch the user specification file (sometimes
refer as profile) form AOS. The SID must be specified in the URL, or
AOS simply returns “false” as result.
Specify “fld” if you wish to fetch certain fields data from AOS. The
list of fields is available with this paper. AOS will not verify the
availability of the field (no error return if the field is not exists).
Refer to User specification table for full list of the field available.
By default (omit use of this parameter), AOS returns the following
fields:-
name,host,group,fullname,apprBody,apprFSize,timezone,languag
e
Return:
A plain text content will be return if the SID is valid.
If the “format” parameter is omitted, the return data will be raw
text, field separated by a Unix Carriage Return (ASCII 10). Eg:
myname
afteroffice.net
My Full Name
.
Note that the field name is not provided in this case. DA should
extract the data based on the default field order, or the field
order specified in the “fld” parameter. If the data contains a
Carriage Return, AOS encode it to “\r”. Is it sometime necessary
to map “\r” back to Carriage Return with curtains fields.
If the “format” parameter is “URL”, the return data will be
formatted to field=data set. Data will be encoded to URL
compatible, eg:
name=myname&host=afteroffice.net&fullname=My%20Full%20Na
me .
Return “false” if SID not specify or expired (user logout).
See also: sqVry
Command sqVry
Syntax:
http://www.afteroffice.com/sqVry.user.mms?sid=SIDxxxxxxxx
Use: Check to see if the SID still valid (user still online). This
command is handy if the DA has implemented some local cache
mechanism to store the user specification data after the first
sqSpec. DA will then only need to issue a sqVry command (faster)
instead of sqSpec to make sure the user session is still valid.
Return: “true” if the SID still valid, “false” if the SID expired or
user logout.
Note:
By default AOS expire user session on 45 minutes of inactivity. If
DA suspect the a user query has expired, issuing sqVry is a way
to find out. In most case DA should validate the SID form time to
time to make sure the data integrity.
See also: sqSpec
Command sqExist
Syntax:
http://www.afteroffice.com/sqExist.user.mms?name=name&host=
host&email=email
Parameters:
name: user login name
host: user host
email (optional): user email
Use: Check to see if there is a user on the AOS database.
Return: “true” if the user exist, “false” if user not exist.
See also: sqVry
Command sqServ
Syntax: http://www.afteroffice.com/sqServ.user.mms?fld=gmt
fld: The fields list that DA would like to obtain data from. It is a
comma separated field name list.
Use: Fetch AOS settings. Works very much like sqServ, just that
this command query the server “profile” instead of active users.
DA may find out some configuration value form the AOS config file.
Refer to AOS config table for field available.
Return: text value
See also: sqSpec
User specification table
Data type:text: String, 8bit ASCIIhtml: text with HTML codingnumber: text in number expressiontime: number, the number of seconds from 1/1/70 2:00AM AOS config table
Extensions
Refer to separate documentation for more information on other API
commands.

Source: http://afteroffice.com/dev/api/AVO_APIv2.pdf