source: trunk/phpgwapi/doc/xmlrpc/phpgw_server.sgml @ 2

Revision 2, 11.3 KB checked in by niltonneto, 17 years ago (diff)

Removida todas as tags usadas pelo CVS ($Id, $Source).
Primeira versão no CVS externo.

  • Property svn:executable set to *
  • Property svn:mime-type set to application/octet-stream
Line 
1<!doctype article public "-//OASIS//DTD DocBook V3.1//EN">
2
3<article lang="en">
4<!-- DocBook file was created by LyX 1.1
5  See http://www.lyx.org/ for more information -->
6  <artheader>
7   <title>
8   eGroupWare XML-RPC/SOAP Methodology
9  </title>
10  <author>
11   (C) 2001-2004 Miles Lott
12   milos@groupwhere.org
13  </author>
14  <date>
15   August 23, 2001 and December 29, 2003
16  </date>
17  <para>
18   additions made September 3, 2001.
19  </para>
20  <para>
21   This document is very preliminary, but describes a working system.
22  </para>
23  </artheader>
24  <sect1>
25   <title>
26   System level requests
27  </title>
28   <sect2>
29    <title>
30    Login and authentication
31   </title>
32   <para>
33    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.
34   </para>
35   <para>
36    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.
37   </para>
38   <para>
39    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 ':'.
40   </para>
41   <para>
42    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.
43   </para>
44    <sect3>
45     <title>
46     system.login
47    </title>
48    <para>
49     The first request a client will make is the system.login method. Here is a sample of a server login packet in XML-RPC:
50    </para>
51    <programlisting>
52<![ CDATA [<?xml version="1.0"?>
53]]><![ CDATA [<methodCall>
54]]><![ CDATA [<methodName>system.login</methodName>
55]]><![ CDATA [<params>
56]]><![ CDATA [<param>
57]]><![ CDATA [<value><struct>
58]]><![ CDATA [<member><name>server_name</name>
59]]><![ CDATA [<value><string>my.host.name</string></value>
60]]><![ CDATA [</member>
61]]><![ CDATA [<member><name>username</name>
62]]><![ CDATA [<value><string>bubba</string></value>
63]]><![ CDATA [</member>
64]]><![ CDATA [<member><name>password</name>
65]]><![ CDATA [<value><string>gump</string></value>
66]]><![ CDATA [</member> </struct></value>
67]]><![ CDATA [</param>
68]]><![ CDATA [</params>
69]]><![ CDATA [</methodCall>
70]]>    </programlisting>
71    <para>
72     And the same in SOAP:
73    </para>
74    <programlisting>
75<![ CDATA [<?xml version="1.0"?>
76]]><![ CDATA [<SOAP-ENV:Envelope
77]]><![ 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"
78]]><![ CDATA [xmlns:ns6="http://soapinterop.org" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
79]]><![ CDATA [<SOAP-ENV:Body> <ns6:system_login>
80]]><![ CDATA [<server_name xsi:type=":string">my.host.name</server_name>
81]]><![ CDATA [<username xsi:type=":string">bubba</username>
82]]><![ CDATA [<password xsi:type=":string">gump</password>
83]]><![ CDATA [</ns6:system_login>
84]]><![ CDATA [</SOAP-ENV:Body>
85]]><![ CDATA [</SOAP-ENV:Envelope>
86]]>    </programlisting>
87    <para>
88     The same style of packet would be required for a user/client login. A successful login should yield the following reply:
89    </para>
90    <programlisting>
91<![ CDATA [<methodResponse>
92]]><![ CDATA [<params>
93]]><![ CDATA [<param>
94]]><![ CDATA [<value><struct>
95]]><![ CDATA [<member><name>sessionid</name>
96]]><![ CDATA [<value><string>cf5c5534307562fc57915608377db007</string></value>
97]]><![ CDATA [</member>
98]]><![ CDATA [<member><name>kp3</name>
99]]><![ CDATA [<value><string>2fe54daa11c8d52116788aa3f93cb70e</string></value>
100]]><![ CDATA [</member>
101]]><![ CDATA [</struct></value>
102]]><![ CDATA [</param>
103]]><![ CDATA [</params>
104]]><![ CDATA [</methodResponse>
105]]>    </programlisting>
106    <para>
107     And a failed login:
108    </para>
109    <programlisting>
110<![ CDATA [<methodResponse>
111]]><![ CDATA [<params>
112]]><![ CDATA [<param>
113]]><![ CDATA [<value><struct>
114]]><![ CDATA [<member><name>GOAWAY</name>
115]]><![ CDATA [<value><string>XOXO</string></value>
116]]><![ CDATA [</member>
117]]><![ CDATA [</struct></value>
118]]><![ CDATA [</param>
119]]><![ CDATA [</params>
120]]><![ CDATA [</methodResponse>
121]]>    </programlisting>
122    <para>
123     eqweqw
124    </para>
125    </sect3>
126    <sect3>
127     <title>
128     system.logout
129    </title>
130    <para>
131     Logout:
132    </para>
133    <programlisting>
134<![ CDATA [<?xml version="1.0"?>
135]]><![ CDATA [<methodCall>
136]]><![ CDATA [<methodName>system.logout</methodName>
137]]><![ CDATA [<params> <param>
138]]><![ CDATA [<value><struct>
139]]><![ CDATA [<member><name>sessionid</name>
140]]><![ CDATA [<value><string>ea35cac53d2c12bd05caecd97304478a</string></value>
141]]><![ CDATA [</member>
142]]><![ CDATA [<member><name>kp3</name>
143]]><![ CDATA [<value><string>4f2b256e0da4e7cbbebaac9f1fc8ca4a</string></value>
144]]><![ CDATA [</member>
145]]><![ CDATA [</struct></value>
146]]><![ CDATA [</param>
147]]><![ CDATA [</params>
148]]><![ CDATA [</methodCall>
149]]>    </programlisting>
150    <para>
151     Logout worked:
152    </para>
153    <programlisting>
154<![ CDATA [<methodResponse>
155]]><![ CDATA [<params>
156]]><![ CDATA [<param>
157]]><![ CDATA [<value><struct>
158]]><![ CDATA [<member><name>GOODBYE</name>
159]]><![ CDATA [<value><string>XOXO</string></value>
160]]><![ CDATA [</member>
161]]><![ CDATA [</struct></value>
162]]><![ CDATA [</param>
163]]><![ CDATA [</params>
164]]><![ CDATA [</methodResponse>
165]]>    </programlisting>
166    </sect3>
167   </sect2>
168  </sect1>
169  <sect1>
170   <title>
171   Business layer requests
172  </title>
173  <para>
174   Once a successful login return packet has been received and sessionid/kp3 have been extracted, every subsequent packet sent to the egroupware server must be preceded by an Authorization header. Here is a sample header:
175  </para>
176  <programlisting>
177<![ CDATA [POST /egroupware/xmlrpc.php HTTP/1.0
178]]><![ CDATA [User-Agent: PHP XMLRPC 1.0
179]]><![ CDATA [Host: my.local.host
180]]><![ CDATA [Authorization: Basic ZDgxNDIyZDRkYjg5NDEyNGNiMzZlMDhhZTdlYzAxZmY6NTU3YzkyYjBmNGE4ZDVlOTUzMzI2YmU2OTQyNjM3YjQ=
181]]><![ CDATA [Content-Type: text/xml
182]]><![ CDATA [Content-Length: 875
183]]>  </programlisting>
184  <para>
185   The longish string is a base64 encoding of the &dollar;sessionid . ':' . &dollar;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:
186  </para>
187  <programlisting>
188<![ CDATA [<?xml version="1.0"?>
189]]><![ CDATA [<methodCall>
190]]><![ CDATA [<methodName>addressbook.boaddressbook.read_entries</methodName>
191]]><![ CDATA [<params>
192]]><![ CDATA [<param>
193]]><![ CDATA [<value><struct>
194]]><![ CDATA [<member><name>start</name>
195]]><![ CDATA [<value><string>1</string></value>
196]]><![ CDATA [</member>
197]]><![ CDATA [<member><name>limit</name>
198]]><![ CDATA [<value><string>5</string></value>
199]]><![ CDATA [</member>
200]]><![ CDATA [<member><name>fields</name>
201]]><![ CDATA [<value><struct>
202]]><![ CDATA [<member><name>n_given</name>
203]]><![ CDATA [<value><string>n_given</string></value>
204]]><![ CDATA [</member>
205]]><![ CDATA [<member><name>n_family</name>
206]]><![ CDATA [<value><string>n_family</string></value>
207]]><![ CDATA [</member>
208]]><![ CDATA [</struct></value>
209]]><![ CDATA [</member>
210]]><![ CDATA [<member><name>query</name>
211]]><![ CDATA [<value><string></string></value>
212]]><![ CDATA [</member>
213]]><![ CDATA [<member><name>filter</name>
214]]><![ CDATA [<value><string></string></value>
215]]><![ CDATA [</member>
216]]><![ CDATA [<member><name>sort</name>
217]]><![ CDATA [<value><string></string></value>
218]]><![ CDATA [</member>
219]]><![ CDATA [<member><name>order</name>
220]]><![ CDATA [<value><string></string></value>
221]]><![ CDATA [</member>
222]]><![ CDATA [</struct></value>
223]]><![ CDATA [</param>
224]]><![ CDATA [</params>
225]]><![ CDATA [</methodCall>
226]]>  </programlisting>
227  <para>
228   Successful response:
229  </para>
230  <programlisting>
231<![ CDATA [<?xml version="1.0"?>
232]]><![ CDATA [<methodResponse>
233]]><![ CDATA [<params>
234]]><![ CDATA [<param>
235]]><![ CDATA [<value><struct>
236]]><![ CDATA [<member><name>0</name>
237]]><![ CDATA [<value><struct>
238]]><![ CDATA [<member><name>id</name>
239]]><![ CDATA [<value><string>1</string></value>
240]]><![ CDATA [</member>
241]]><![ CDATA [<member><name>lid</name>
242]]><![ CDATA [<value><string></string></value>
243]]><![ CDATA [</member>
244]]><![ CDATA [<member><name>tid</name>
245]]><![ CDATA [<value><string>n</string></value>
246]]><![ CDATA [</member>
247]]><![ CDATA [<member><name>owner</name>
248]]><![ CDATA [<value><string>500</string></value>
249]]><![ CDATA [</member>
250]]><![ CDATA [<member><name>access</name>
251]]><![ CDATA [<value><string>private</string></value>
252]]><![ CDATA [</member>
253]]><![ CDATA [<member><name>cat_id</name>
254]]><![ CDATA [<value><string>1</string></value>
255]]><![ CDATA [</member>
256]]><![ CDATA [<member><name>n_given</name>
257]]><![ CDATA [<value><string>Alan</string></value>
258]]><![ CDATA [</member>
259]]><![ CDATA [</struct></value>
260]]><![ CDATA [</member>
261]]><![ CDATA [<member><name>1</name>
262]]><![ CDATA [<value><struct>
263]]><![ CDATA [<member><name>id</name>
264]]><![ CDATA [<value><string>2</string></value>
265]]><![ CDATA [</member>
266]]><![ CDATA [<member><name>lid</name>
267]]><![ CDATA [<value><string></string></value>
268]]><![ CDATA [</member>
269]]><![ CDATA [<member><name>tid</name>
270]]><![ CDATA [<value><string>n</string></value>
271]]><![ CDATA [</member>
272]]><![ CDATA [<member><name>owner</name>
273]]><![ CDATA [<value><string>500</string></value>
274]]><![ CDATA [</member>
275]]><![ CDATA [<member><name>access</name>
276]]><![ CDATA [<value><string>private</string></value>
277]]><![ CDATA [</member>
278]]><![ CDATA [<member><name>cat_id</name>
279]]><![ CDATA [<value><string>1</string></value>
280]]><![ CDATA [</member>
281]]><![ CDATA [<member><name>n_given</name>
282]]><![ CDATA [<value><string>Andy</string></value>
283]]><![ CDATA [</member>
284]]><![ CDATA [</struct></value>
285]]><![ CDATA [</member>
286]]><![ CDATA [...
287]]>  </programlisting>
288  <para>
289   Unauthorized access attempt returns:
290  </para>
291  <programlisting>
292<![ CDATA [<methodResponse>
293]]><![ CDATA [<params>
294]]><![ CDATA [<param>
295]]><![ CDATA [<value><string>UNAUTHORIZED</string></value>
296]]><![ CDATA [</param>
297]]><![ CDATA [</params>
298]]><![ CDATA [</methodResponse>
299]]>  </programlisting>
300  </sect1>
301  <sect1>
302   <title>
303   More to come...
304  </title>
305  <para>
306   Documenting every single call will be difficult, but should be done. In leiu of this, please see the class.bo&lcub;APPNAME&rcub;.inc.php files in each application/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.
307  </para>
308  </sect1>
309
310
311</article>
Note: See TracBrowser for help on using the repository browser.