egroupware/phpgwapi/doc/xmlrpc/phpgw_server.lyx

#LyX 1.1 created this file. For more info see http://www.lyx.org/
\lyxformat 218
\textclass docbook
\language english
\inputencoding auto
\fontscheme default
\graphics default
\paperfontsize default
\spacing single 
\papersize Default
\paperpackage a4
\use_geometry 0
\use_amsmath 0
\paperorientation portrait
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\defskip medskip
\quotes_language english
\quotes_times 2
\papercolumns 1
\papersides 1
\paperpagestyle default

\layout Title

eGroupWare XML-RPC/SOAP Methodology
\layout Author

(C) 2001-2004 Miles Lott
\layout Author

milos@groupwhere.org
\layout Date

August 23, 2001 and December 29, 2003
\layout Standard

additions made September 3, 2001.
\layout Standard

This document is very preliminary, but describes a working system.
\layout Section

System level requests
\layout Subsection

Login and authentication
\layout Standard

Authentication for user logins is handled internally no differently than
 for the typical eGroupWare login via web browser.
 Server logins, added for XML-RPC and SOAP, are only slightly different.
 For either protocol, user and server login and authentication and subsequent
 requests are handled by their respective server apps, xmlrpc.php and soap.php.
 A server is identified by a custom HTTP header, without which a normal
 user login will be undertaken.
\layout Standard

A client or server sends the appropriate XML-RPC or SOAP packet containing
 host, user, and password information to the phpgw server.
 The server then assigns a sessionid and key, which is returned to the client
 in the appropriate format.
\layout Standard

Our current method for authenticating requests after successful login is
 via the Authorization: Basic HTTP header to be sent by the client or requesting
 server.
 The format of this header is a base64 encoding of the assigned sessionid
 and kp3 variables, seperated by a ':'.
\layout Standard

Further security may be obtained by using SSL on the client and server.
 In the future, we may encrypt/descrypt the data on either end, or at least
 provide this as an option.
 The sessionid and key variables will make this possible, and relatively
 secure.
\layout Subsubsection

system.login
\layout Standard

The first request a client will make is the system.login method.
 Here is a sample of a server login packet in XML-RPC:
\layout Code

<?xml version="1.0"?>
\layout Code

<methodCall>
\layout Code

<methodName>system.login</methodName>
\layout Code

<params>
\layout Code

<param>
\layout Code

<value><struct>
\layout Code

<member><name>server_name</name>
\layout Code

<value><string>my.host.name</string></value>
\layout Code

</member>
\layout Code

<member><name>username</name>
\layout Code

<value><string>bubba</string></value>
\layout Code

</member>
\layout Code

<member><name>password</name>
\layout Code

<value><string>gump</string></value>
\layout Code

</member> </struct></value>
\layout Code

</param>
\layout Code

</params>
\layout Code

</methodCall>
\layout Standard

And the same in SOAP:
\layout Code

<?xml version="1.0"?>
\layout Code

<SOAP-ENV:Envelope
\layout Code

xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.
org/1999/XMLSchema-instance" xmlns:xsd="http://www.w3.org/1999/XMLSchema"
 xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:si="http://soapi
nterop.org/xsd"
\layout Code

xmlns:ns6="http://soapinterop.org" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.o
rg/soap/encoding/">
\layout Code

<SOAP-ENV:Body> <ns6:system_login>
\layout Code

<server_name xsi:type=":string">my.host.name</server_name>
\layout Code

<username xsi:type=":string">bubba</username>
\layout Code

<password xsi:type=":string">gump</password>
\layout Code

</ns6:system_login>
\layout Code

</SOAP-ENV:Body>
\layout Code

</SOAP-ENV:Envelope>
\layout Standard

The same style of packet would be required for a user/client login.
 A successful login should yield the following reply:
\layout Code

<methodResponse>
\layout Code

<params>
\layout Code

<param>
\layout Code

<value><struct>
\layout Code

<member><name>sessionid</name>
\layout Code

<value><string>cf5c5534307562fc57915608377db007</string></value>
\layout Code

</member>
\layout Code

<member><name>kp3</name>
\layout Code

<value><string>2fe54daa11c8d52116788aa3f93cb70e</string></value>
\layout Code

</member>
\layout Code

</struct></value>
\layout Code

</param>
\layout Code

</params>
\layout Code

</methodResponse>
\layout Standard

And a failed login:
\layout Code

<methodResponse>
\layout Code

<params>
\layout Code

<param>
\layout Code

<value><struct>
\layout Code

<member><name>GOAWAY</name>
\layout Code

<value><string>XOXO</string></value>
\layout Code

</member>
\layout Code

</struct></value>
\layout Code

</param>
\layout Code

</params>
\layout Code

</methodResponse>
\layout Standard

eqweqw
\layout Subsubsection

system.logout
\layout Standard

Logout:
\layout Code

<?xml version="1.0"?>
\layout Code

<methodCall>
\layout Code

<methodName>system.logout</methodName>
\layout Code

<params> <param>
\layout Code

<value><struct>
\layout Code

<member><name>sessionid</name>
\layout Code

<value><string>ea35cac53d2c12bd05caecd97304478a</string></value>
\layout Code

</member>
\layout Code

<member><name>kp3</name>
\layout Code

<value><string>4f2b256e0da4e7cbbebaac9f1fc8ca4a</string></value>
\layout Code

</member>
\layout Code

</struct></value>
\layout Code

</param>
\layout Code

</params>
\layout Code

</methodCall>
\layout Standard

Logout worked:
\layout Code

<methodResponse>
\layout Code

<params>
\layout Code

<param>
\layout Code

<value><struct>
\layout Code

<member><name>GOODBYE</name>
\layout Code

<value><string>XOXO</string></value>
\layout Code

</member>
\layout Code

</struct></value>
\layout Code

</param>
\layout Code

</params>
\layout Code

</methodResponse>
\layout Section

Business layer requests
\layout Standard

Once a successful login return packet has been received and sessionid/kp3
 have been extracted, every subsequent packet sent to the phpgroupware server
 must be preceded by an Authorization header.
 Here is a sample header:
\layout Code

POST /phpgroupware/xmlrpc.php HTTP/1.0
\layout Code

User-Agent: PHP XMLRPC 1.0
\layout Code

Host: my.local.host
\layout Code

Authorization: Basic ZDgxNDIyZDRkYjg5NDEyNGNiMzZlMDhhZTdlYzAxZmY6NTU3YzkyYjBmNGE
4ZDVlOTUzMzI2YmU2OTQyNjM3YjQ=
\layout Code

Content-Type: text/xml
\layout Code

Content-Length: 875
\layout Standard

The longish string is a base64 encoding of the $sessionid .
 ':' .
 $kp3.
 For now this is our only supported authentication method.
 Additional methods would probably also affect the methodCalls.
 This is certainly open to discussion.
 Following is a typical request for some contact data:
\layout Code

<?xml version="1.0"?>
\layout Code

<methodCall>
\layout Code

<methodName>addressbook.boaddressbook.read_entries</methodName>
\layout Code

<params>
\layout Code

<param>
\layout Code

<value><struct>
\layout Code

<member><name>start</name>
\layout Code

<value><string>1</string></value>
\layout Code

</member>
\layout Code

<member><name>limit</name>
\layout Code

<value><string>5</string></value>
\layout Code

</member>
\layout Code

<member><name>fields</name>
\layout Code

<value><struct>
\layout Code

<member><name>n_given</name>
\layout Code

<value><string>n_given</string></value>
\layout Code

</member>
\layout Code

<member><name>n_family</name>
\layout Code

<value><string>n_family</string></value>
\layout Code

</member>
\layout Code

</struct></value>
\layout Code

</member>
\layout Code

<member><name>query</name>
\layout Code

<value><string></string></value>
\layout Code

</member>
\layout Code

<member><name>filter</name>
\layout Code

<value><string></string></value>
\layout Code

</member>
\layout Code

<member><name>sort</name>
\layout Code

<value><string></string></value>
\layout Code

</member>
\layout Code

<member><name>order</name>
\layout Code

<value><string></string></value>
\layout Code

</member>
\layout Code

</struct></value>
\layout Code

</param>
\layout Code

</params>
\layout Code

</methodCall>
\layout Standard

Successful response:
\layout Code

<?xml version="1.0"?>
\layout Code

<methodResponse>
\layout Code

<params> 
\layout Code

<param>
\layout Code

<value><struct>
\layout Code

<member><name>0</name>
\layout Code

<value><struct> 
\layout Code

<member><name>id</name>
\layout Code

<value><string>1</string></value>
\layout Code

</member>
\layout Code

<member><name>lid</name>
\layout Code

<value><string></string></value>
\layout Code

</member>
\layout Code

<member><name>tid</name> 
\layout Code

<value><string>n</string></value> 
\layout Code

</member>
\layout Code

<member><name>owner</name> 
\layout Code

<value><string>500</string></value> 
\layout Code

</member>
\layout Code

<member><name>access</name>
\layout Code

<value><string>private</string></value> 
\layout Code

</member>
\layout Code

<member><name>cat_id</name> 
\layout Code

<value><string>1</string></value> 
\layout Code

</member> 
\layout Code

<member><name>n_given</name> 
\layout Code

<value><string>Alan</string></value> 
\layout Code

</member> 
\layout Code

</struct></value> 
\layout Code

</member> 
\layout Code

<member><name>1</name>
\layout Code

<value><struct>
\layout Code

<member><name>id</name>
\layout Code

<value><string>2</string></value>
\layout Code

</member>
\layout Code

<member><name>lid</name>
\layout Code

<value><string></string></value>
\layout Code

</member>
\layout Code

<member><name>tid</name>
\layout Code

<value><string>n</string></value>
\layout Code

</member>
\layout Code

<member><name>owner</name>
\layout Code

<value><string>500</string></value>
\layout Code

</member>
\layout Code

<member><name>access</name>
\layout Code

<value><string>private</string></value>
\layout Code

</member>
\layout Code

<member><name>cat_id</name>
\layout Code

<value><string>1</string></value>
\layout Code

</member>
\layout Code

<member><name>n_given</name>
\layout Code

<value><string>Andy</string></value>
\layout Code

</member>
\layout Code

</struct></value>
\layout Code

</member>
\layout Code

...
\layout Standard

Unauthorized access attempt returns:
\layout Code

<methodResponse>
\layout Code

<params>
\layout Code

<param>
\layout Code

<value><string>UNAUTHORIZED</string></value>
\layout Code

</param>
\layout Code

</params>
\layout Code

</methodResponse>
\layout Section

More to come...
\layout Standard

Documenting every single call will be difficult, but should be done.
 In leiu of this, please see the class.bo{APPNAME}.inc.php files in each applicatio
n/inc directory in the egroupware cvs.
 In this file will be a list_methods() function, which returns the information
 to the server about input/output structure for each call.
 If the file does not have this function, then it is not yet workable via
 this interface.
 As for the actual functions, they are also in this file.
 Generally, they will all accept associative array input and return same,
 but not always.
 This code is in flux, have fun.
\the_end