[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Phpgroupware-cvs] phpgwapi/doc/xmlrpc/phpgw_server.sgml, 1.3
|
From: |
nomail |
|
Subject: |
[Phpgroupware-cvs] phpgwapi/doc/xmlrpc/phpgw_server.sgml, 1.3 |
|
Date: |
Thu, 30 Dec 2004 07:47:30 +0100 |
Update of /phpgwapi/doc/xmlrpc
Added Files:
Branch:
phpgw_server.sgml
date: 2004/12/30 06:47:30; author: skwashd; state: Exp; lines: +0 -0
Log Message:
new HEAD
=====================================================================
<!doctype article public "-//OASIS//DTD DocBook V3.1//EN">
<article lang="en">
<!-- DocBook file was created by LyX 1.1
See http://www.lyx.org/ for more information -->
<artheader>
<title>
phpGroupWare XML-RPC/SOAP Methodology
</title>
<author>
Miles Lott
address@hidden
</author>
<date>
August 23, 2001
</date>
<para>
additions made September 3, 2001.
</para>
<para>
This document is very preliminary, but describes a working system.
</para>
</artheader>
<sect1>
<title>
System level requests
</title>
<sect2>
<title>
Login and authentication
</title>
<para>
Authentication for user logins is handled internally no differently than
for the typical phpGroupWare 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.
</para>
<para>
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.
</para>
<para>
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 ':'.
</para>
<para>
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.
</para>
<sect3>
<title>
system.login
</title>
<para>
The first request a client will make is the system.login method. Here is a
sample of a server login packet in XML-RPC:
</para>
<programlisting>
<![ CDATA [<?xml version="1.0"?>
]]><![ CDATA [<methodCall>
]]><![ CDATA [<methodName>system.login</methodName>
]]><![ CDATA [<params>
]]><![ CDATA [<param>
]]><![ CDATA [<value><struct>
]]><![ CDATA [<member><name>server_name</name>
]]><![ CDATA [<value><string>my.host.name</string></value>
]]><![ CDATA [</member>
]]><![ CDATA [<member><name>username</name>
]]><![ CDATA [<value><string>bubba</string></value>
]]><![ CDATA [</member>
]]><![ CDATA [<member><name>password</name>
]]><![ CDATA [<value><string>gump</string></value>
]]><![ CDATA [</member> </struct></value>
]]><![ CDATA [</param>
]]><![ CDATA [</params>
]]><![ CDATA [</methodCall>
]]> </programlisting>
<para>
And the same in SOAP:
</para>
<programlisting>
<![ CDATA [<?xml version="1.0"?>
]]><![ CDATA [<SOAP-ENV:Envelope
]]><![ CDATA [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://soapinterop.org/xsd";
]]><![ CDATA [xmlns:ns6="http://soapinterop.org";
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/";>
]]><![ CDATA [<SOAP-ENV:Body> <ns6:system_login>
]]><![ CDATA [<server_name xsi:type=":string">my.host.name</server_name>
]]><![ CDATA [<username xsi:type=":string">bubba</username>
]]><![ CDATA [<password xsi:type=":string">gump</password>
]]><![ CDATA [</ns6:system_login>
]]><![ CDATA [</SOAP-ENV:Body>
]]><![ CDATA [</SOAP-ENV:Envelope>
]]> </programlisting>
<para>
The same style of packet would be required for a user/client login. A
successful login should yield the following reply:
</para>
<programlisting>
<![ CDATA [<methodResponse>
]]><![ CDATA [<params>
]]><![ CDATA [<param>
]]><![ CDATA [<value><struct>
]]><![ CDATA [<member><name>sessionid</name>
]]><![ CDATA [<value><string>cf5c5534307562fc57915608377db007</string></value>
]]><![ CDATA [</member>
]]><![ CDATA [<member><name>kp3</name>
]]><![ CDATA [<value><string>2fe54daa11c8d52116788aa3f93cb70e</string></value>
]]><![ CDATA [</member>
]]><![ CDATA [</struct></value>
]]><![ CDATA [</param>
]]><![ CDATA [</params>
]]><![ CDATA [</methodResponse>
]]> </programlisting>
<para>
And a failed login:
</para>
<programlisting>
<![ CDATA [<methodResponse>
]]><![ CDATA [<params>
]]><![ CDATA [<param>
]]><![ CDATA [<value><struct>
]]><![ CDATA [<member><name>GOAWAY</name>
]]><![ CDATA [<value><string>XOXO</string></value>
]]><![ CDATA [</member>
]]><![ CDATA [</struct></value>
]]><![ CDATA [</param>
]]><![ CDATA [</params>
]]><![ CDATA [</methodResponse>
]]> </programlisting>
<para>
eqweqw
</para>
</sect3>
<sect3>
<title>
system.logout
</title>
<para>
Logout:
</para>
<programlisting>
<![ CDATA [<?xml version="1.0"?>
]]><![ CDATA [<methodCall>
]]><![ CDATA [<methodName>system.logout</methodName>
]]><![ CDATA [<params> <param>
]]><![ CDATA [<value><struct>
]]><![ CDATA [<member><name>sessionid</name>
]]><![ CDATA [<value><string>ea35cac53d2c12bd05caecd97304478a</string></value>
]]><![ CDATA [</member>
]]><![ CDATA [<member><name>kp3</name>
]]><![ CDATA [<value><string>4f2b256e0da4e7cbbebaac9f1fc8ca4a</string></value>
]]><![ CDATA [</member>
]]><![ CDATA [</struct></value>
]]><![ CDATA [</param>
]]><![ CDATA [</params>
]]><![ CDATA [</methodCall>
]]> </programlisting>
<para>
Logout worked:
</para>
<programlisting>
<![ CDATA [<methodResponse>
]]><![ CDATA [<params>
]]><![ CDATA [<param>
]]><![ CDATA [<value><struct>
]]><![ CDATA [<member><name>GOODBYE</name>
]]><![ CDATA [<value><string>XOXO</string></value>
]]><![ CDATA [</member>
]]><![ CDATA [</struct></value>
]]><![ CDATA [</param>
]]><![ CDATA [</params>
]]><![ CDATA [</methodResponse>
]]> </programlisting>
</sect3>
</sect2>
</sect1>
<sect1>
<title>
Business layer requests
</title>
<para>
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:
</para>
<programlisting>
<![ CDATA [POST /phpgroupware/xmlrpc.php HTTP/1.0
]]><![ CDATA [User-Agent: PHP XMLRPC 1.0
]]><![ CDATA [Host: my.local.host
]]><![ CDATA [Authorization: Basic
ZDgxNDIyZDRkYjg5NDEyNGNiMzZlMDhhZTdlYzAxZmY6NTU3YzkyYjBmNGE4ZDVlOTUzMzI2YmU2OTQyNjM3YjQ=
]]><![ CDATA [Content-Type: text/xml
]]><![ CDATA [Content-Length: 875
]]> </programlisting>
<para>
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:
</para>
<programlisting>
<![ CDATA [<?xml version="1.0"?>
]]><![ CDATA [<methodCall>
]]><![ CDATA [<methodName>addressbook.boaddressbook.read_entries</methodName>
]]><![ CDATA [<params>
]]><![ CDATA [<param>
]]><![ CDATA [<value><struct>
]]><![ CDATA [<member><name>start</name>
]]><![ CDATA [<value><string>1</string></value>
]]><![ CDATA [</member>
]]><![ CDATA [<member><name>limit</name>
]]><![ CDATA [<value><string>5</string></value>
]]><![ CDATA [</member>
]]><![ CDATA [<member><name>fields</name>
]]><![ CDATA [<value><struct>
]]><![ CDATA [<member><name>n_given</name>
]]><![ CDATA [<value><string>n_given</string></value>
]]><![ CDATA [</member>
]]><![ CDATA [<member><name>n_family</name>
]]><![ CDATA [<value><string>n_family</string></value>
]]><![ CDATA [</member>
]]><![ CDATA [</struct></value>
]]><![ CDATA [</member>
]]><![ CDATA [<member><name>query</name>
]]><![ CDATA [<value><string></string></value>
]]><![ CDATA [</member>
]]><![ CDATA [<member><name>filter</name>
]]><![ CDATA [<value><string></string></value>
]]><![ CDATA [</member>
]]><![ CDATA [<member><name>sort</name>
]]><![ CDATA [<value><string></string></value>
]]><![ CDATA [</member>
]]><![ CDATA [<member><name>order</name>
]]><![ CDATA [<value><string></string></value>
]]><![ CDATA [</member>
]]><![ CDATA [</struct></value>
]]><![ CDATA [</param>
]]><![ CDATA [</params>
]]><![ CDATA [</methodCall>
]]> </programlisting>
<para>
Successful response:
</para>
<programlisting>
<![ CDATA [<?xml version="1.0"?>
]]><![ CDATA [<methodResponse>
]]><![ CDATA [<params>
]]><![ CDATA [<param>
]]><![ CDATA [<value><struct>
]]><![ CDATA [<member><name>0</name>
]]><![ CDATA [<value><struct>
]]><![ CDATA [<member><name>id</name>
]]><![ CDATA [<value><string>1</string></value>
]]><![ CDATA [</member>
]]><![ CDATA [<member><name>lid</name>
]]><![ CDATA [<value><string></string></value>
]]><![ CDATA [</member>
]]><![ CDATA [<member><name>tid</name>
]]><![ CDATA [<value><string>n</string></value>
]]><![ CDATA [</member>
]]><![ CDATA [<member><name>owner</name>
]]><![ CDATA [<value><string>500</string></value>
]]><![ CDATA [</member>
]]><![ CDATA [<member><name>access</name>
]]><![ CDATA [<value><string>private</string></value>
]]><![ CDATA [</member>
]]><![ CDATA [<member><name>cat_id</name>
]]><![ CDATA [<value><string>1</string></value>
]]><![ CDATA [</member>
]]><![ CDATA [<member><name>n_given</name>
]]><![ CDATA [<value><string>Alan</string></value>
]]><![ CDATA [</member>
]]><![ CDATA [</struct></value>
]]><![ CDATA [</member>
]]><![ CDATA [<member><name>1</name>
]]><![ CDATA [<value><struct>
]]><![ CDATA [<member><name>id</name>
]]><![ CDATA [<value><string>2</string></value>
]]><![ CDATA [</member>
]]><![ CDATA [<member><name>lid</name>
]]><![ CDATA [<value><string></string></value>
]]><![ CDATA [</member>
]]><![ CDATA [<member><name>tid</name>
]]><![ CDATA [<value><string>n</string></value>
]]><![ CDATA [</member>
]]><![ CDATA [<member><name>owner</name>
]]><![ CDATA [<value><string>500</string></value>
]]><![ CDATA [</member>
]]><![ CDATA [<member><name>access</name>
]]><![ CDATA [<value><string>private</string></value>
]]><![ CDATA [</member>
]]><![ CDATA [<member><name>cat_id</name>
]]><![ CDATA [<value><string>1</string></value>
]]><![ CDATA [</member>
]]><![ CDATA [<member><name>n_given</name>
]]><![ CDATA [<value><string>Andy</string></value>
]]><![ CDATA [</member>
]]><![ CDATA [</struct></value>
]]><![ CDATA [</member>
]]><![ CDATA [...
]]> </programlisting>
<para>
Unauthorized access attempt returns:
</para>
<programlisting>
<![ CDATA [<methodResponse>
]]><![ CDATA [<params>
]]><![ CDATA [<param>
]]><![ CDATA [<value><string>UNAUTHORIZED</string></value>
]]><![ CDATA [</param>
]]><![ CDATA [</params>
]]><![ CDATA [</methodResponse>
]]> </programlisting>
</sect1>
<sect1>
<title>
More to come...
</title>
<para>
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
application/inc directory in the phpgroupware 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.
</para>
</sect1>
</article>
- [Phpgroupware-cvs] phpgwapi/doc/xmlrpc/phpgw_server.sgml, 1.3,
nomail <=