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

Revision 2, 10.9 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#LyX 1.1 created this file. For more info see http://www.lyx.org/
2\lyxformat 218
3\textclass docbook
4\language english
5\inputencoding auto
6\fontscheme default
7\graphics default
8\paperfontsize default
9\spacing single
10\papersize Default
11\paperpackage a4
12\use_geometry 0
13\use_amsmath 0
14\paperorientation portrait
15\secnumdepth 3
16\tocdepth 3
17\paragraph_separation indent
18\defskip medskip
19\quotes_language english
20\quotes_times 2
21\papercolumns 1
22\papersides 1
23\paperpagestyle default
24
25\layout Title
26
27eGroupWare XML-RPC/SOAP Methodology
28\layout Author
29
30(C) 2001-2004 Miles Lott
31\layout Author
32
33milos@groupwhere.org
34\layout Date
35
36August 23, 2001 and December 29, 2003
37\layout Standard
38
39additions made September 3, 2001.
40\layout Standard
41
42This document is very preliminary, but describes a working system.
43\layout Section
44
45System level requests
46\layout Subsection
47
48Login and authentication
49\layout Standard
50
51Authentication for user logins is handled internally no differently than
52 for the typical eGroupWare login via web browser.
53 Server logins, added for XML-RPC and SOAP, are only slightly different.
54 For either protocol, user and server login and authentication and subsequent
55 requests are handled by their respective server apps, xmlrpc.php and soap.php.
56 A server is identified by a custom HTTP header, without which a normal
57 user login will be undertaken.
58\layout Standard
59
60A client or server sends the appropriate XML-RPC or SOAP packet containing
61 host, user, and password information to the phpgw server.
62 The server then assigns a sessionid and key, which is returned to the client
63 in the appropriate format.
64\layout Standard
65
66Our current method for authenticating requests after successful login is
67 via the Authorization: Basic HTTP header to be sent by the client or requesting
68 server.
69 The format of this header is a base64 encoding of the assigned sessionid
70 and kp3 variables, seperated by a ':'.
71\layout Standard
72
73Further security may be obtained by using SSL on the client and server.
74 In the future, we may encrypt/descrypt the data on either end, or at least
75 provide this as an option.
76 The sessionid and key variables will make this possible, and relatively
77 secure.
78\layout Subsubsection
79
80system.login
81\layout Standard
82
83The first request a client will make is the system.login method.
84 Here is a sample of a server login packet in XML-RPC:
85\layout Code
86
87<?xml version="1.0"?>
88\layout Code
89
90<methodCall>
91\layout Code
92
93<methodName>system.login</methodName>
94\layout Code
95
96<params>
97\layout Code
98
99<param>
100\layout Code
101
102<value><struct>
103\layout Code
104
105<member><name>server_name</name>
106\layout Code
107
108<value><string>my.host.name</string></value>
109\layout Code
110
111</member>
112\layout Code
113
114<member><name>username</name>
115\layout Code
116
117<value><string>bubba</string></value>
118\layout Code
119
120</member>
121\layout Code
122
123<member><name>password</name>
124\layout Code
125
126<value><string>gump</string></value>
127\layout Code
128
129</member> </struct></value>
130\layout Code
131
132</param>
133\layout Code
134
135</params>
136\layout Code
137
138</methodCall>
139\layout Standard
140
141And the same in SOAP:
142\layout Code
143
144<?xml version="1.0"?>
145\layout Code
146
147<SOAP-ENV:Envelope
148\layout Code
149
150xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.
151org/1999/XMLSchema-instance" xmlns:xsd="http://www.w3.org/1999/XMLSchema"
152 xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:si="http://soapi
153nterop.org/xsd"
154\layout Code
155
156xmlns:ns6="http://soapinterop.org" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.o
157rg/soap/encoding/">
158\layout Code
159
160<SOAP-ENV:Body> <ns6:system_login>
161\layout Code
162
163<server_name xsi:type=":string">my.host.name</server_name>
164\layout Code
165
166<username xsi:type=":string">bubba</username>
167\layout Code
168
169<password xsi:type=":string">gump</password>
170\layout Code
171
172</ns6:system_login>
173\layout Code
174
175</SOAP-ENV:Body>
176\layout Code
177
178</SOAP-ENV:Envelope>
179\layout Standard
180
181The same style of packet would be required for a user/client login.
182 A successful login should yield the following reply:
183\layout Code
184
185<methodResponse>
186\layout Code
187
188<params>
189\layout Code
190
191<param>
192\layout Code
193
194<value><struct>
195\layout Code
196
197<member><name>sessionid</name>
198\layout Code
199
200<value><string>cf5c5534307562fc57915608377db007</string></value>
201\layout Code
202
203</member>
204\layout Code
205
206<member><name>kp3</name>
207\layout Code
208
209<value><string>2fe54daa11c8d52116788aa3f93cb70e</string></value>
210\layout Code
211
212</member>
213\layout Code
214
215</struct></value>
216\layout Code
217
218</param>
219\layout Code
220
221</params>
222\layout Code
223
224</methodResponse>
225\layout Standard
226
227And a failed login:
228\layout Code
229
230<methodResponse>
231\layout Code
232
233<params>
234\layout Code
235
236<param>
237\layout Code
238
239<value><struct>
240\layout Code
241
242<member><name>GOAWAY</name>
243\layout Code
244
245<value><string>XOXO</string></value>
246\layout Code
247
248</member>
249\layout Code
250
251</struct></value>
252\layout Code
253
254</param>
255\layout Code
256
257</params>
258\layout Code
259
260</methodResponse>
261\layout Standard
262
263eqweqw
264\layout Subsubsection
265
266system.logout
267\layout Standard
268
269Logout:
270\layout Code
271
272<?xml version="1.0"?>
273\layout Code
274
275<methodCall>
276\layout Code
277
278<methodName>system.logout</methodName>
279\layout Code
280
281<params> <param>
282\layout Code
283
284<value><struct>
285\layout Code
286
287<member><name>sessionid</name>
288\layout Code
289
290<value><string>ea35cac53d2c12bd05caecd97304478a</string></value>
291\layout Code
292
293</member>
294\layout Code
295
296<member><name>kp3</name>
297\layout Code
298
299<value><string>4f2b256e0da4e7cbbebaac9f1fc8ca4a</string></value>
300\layout Code
301
302</member>
303\layout Code
304
305</struct></value>
306\layout Code
307
308</param>
309\layout Code
310
311</params>
312\layout Code
313
314</methodCall>
315\layout Standard
316
317Logout worked:
318\layout Code
319
320<methodResponse>
321\layout Code
322
323<params>
324\layout Code
325
326<param>
327\layout Code
328
329<value><struct>
330\layout Code
331
332<member><name>GOODBYE</name>
333\layout Code
334
335<value><string>XOXO</string></value>
336\layout Code
337
338</member>
339\layout Code
340
341</struct></value>
342\layout Code
343
344</param>
345\layout Code
346
347</params>
348\layout Code
349
350</methodResponse>
351\layout Section
352
353Business layer requests
354\layout Standard
355
356Once a successful login return packet has been received and sessionid/kp3
357 have been extracted, every subsequent packet sent to the egroupware server
358 must be preceded by an Authorization header.
359 Here is a sample header:
360\layout Code
361
362POST /egroupware/xmlrpc.php HTTP/1.0
363\layout Code
364
365User-Agent: PHP XMLRPC 1.0
366\layout Code
367
368Host: my.local.host
369\layout Code
370
371Authorization: Basic ZDgxNDIyZDRkYjg5NDEyNGNiMzZlMDhhZTdlYzAxZmY6NTU3YzkyYjBmNGE
3724ZDVlOTUzMzI2YmU2OTQyNjM3YjQ=
373\layout Code
374
375Content-Type: text/xml
376\layout Code
377
378Content-Length: 875
379\layout Standard
380
381The longish string is a base64 encoding of the $sessionid .
382 ':' .
383 $kp3.
384 For now this is our only supported authentication method.
385 Additional methods would probably also affect the methodCalls.
386 This is certainly open to discussion.
387 Following is a typical request for some contact data:
388\layout Code
389
390<?xml version="1.0"?>
391\layout Code
392
393<methodCall>
394\layout Code
395
396<methodName>addressbook.boaddressbook.read_entries</methodName>
397\layout Code
398
399<params>
400\layout Code
401
402<param>
403\layout Code
404
405<value><struct>
406\layout Code
407
408<member><name>start</name>
409\layout Code
410
411<value><string>1</string></value>
412\layout Code
413
414</member>
415\layout Code
416
417<member><name>limit</name>
418\layout Code
419
420<value><string>5</string></value>
421\layout Code
422
423</member>
424\layout Code
425
426<member><name>fields</name>
427\layout Code
428
429<value><struct>
430\layout Code
431
432<member><name>n_given</name>
433\layout Code
434
435<value><string>n_given</string></value>
436\layout Code
437
438</member>
439\layout Code
440
441<member><name>n_family</name>
442\layout Code
443
444<value><string>n_family</string></value>
445\layout Code
446
447</member>
448\layout Code
449
450</struct></value>
451\layout Code
452
453</member>
454\layout Code
455
456<member><name>query</name>
457\layout Code
458
459<value><string></string></value>
460\layout Code
461
462</member>
463\layout Code
464
465<member><name>filter</name>
466\layout Code
467
468<value><string></string></value>
469\layout Code
470
471</member>
472\layout Code
473
474<member><name>sort</name>
475\layout Code
476
477<value><string></string></value>
478\layout Code
479
480</member>
481\layout Code
482
483<member><name>order</name>
484\layout Code
485
486<value><string></string></value>
487\layout Code
488
489</member>
490\layout Code
491
492</struct></value>
493\layout Code
494
495</param>
496\layout Code
497
498</params>
499\layout Code
500
501</methodCall>
502\layout Standard
503
504Successful response:
505\layout Code
506
507<?xml version="1.0"?>
508\layout Code
509
510<methodResponse>
511\layout Code
512
513<params> 
514\layout Code
515
516<param>
517\layout Code
518
519<value><struct>
520\layout Code
521
522<member><name>0</name>
523\layout Code
524
525<value><struct> 
526\layout Code
527
528<member><name>id</name>
529\layout Code
530
531<value><string>1</string></value>
532\layout Code
533
534</member>
535\layout Code
536
537<member><name>lid</name>
538\layout Code
539
540<value><string></string></value>
541\layout Code
542
543</member>
544\layout Code
545
546<member><name>tid</name> 
547\layout Code
548
549<value><string>n</string></value> 
550\layout Code
551
552</member>
553\layout Code
554
555<member><name>owner</name> 
556\layout Code
557
558<value><string>500</string></value> 
559\layout Code
560
561</member>
562\layout Code
563
564<member><name>access</name>
565\layout Code
566
567<value><string>private</string></value> 
568\layout Code
569
570</member>
571\layout Code
572
573<member><name>cat_id</name> 
574\layout Code
575
576<value><string>1</string></value> 
577\layout Code
578
579</member>
580\layout Code
581
582<member><name>n_given</name> 
583\layout Code
584
585<value><string>Alan</string></value> 
586\layout Code
587
588</member>
589\layout Code
590
591</struct></value>
592\layout Code
593
594</member>
595\layout Code
596
597<member><name>1</name>
598\layout Code
599
600<value><struct>
601\layout Code
602
603<member><name>id</name>
604\layout Code
605
606<value><string>2</string></value>
607\layout Code
608
609</member>
610\layout Code
611
612<member><name>lid</name>
613\layout Code
614
615<value><string></string></value>
616\layout Code
617
618</member>
619\layout Code
620
621<member><name>tid</name>
622\layout Code
623
624<value><string>n</string></value>
625\layout Code
626
627</member>
628\layout Code
629
630<member><name>owner</name>
631\layout Code
632
633<value><string>500</string></value>
634\layout Code
635
636</member>
637\layout Code
638
639<member><name>access</name>
640\layout Code
641
642<value><string>private</string></value>
643\layout Code
644
645</member>
646\layout Code
647
648<member><name>cat_id</name>
649\layout Code
650
651<value><string>1</string></value>
652\layout Code
653
654</member>
655\layout Code
656
657<member><name>n_given</name>
658\layout Code
659
660<value><string>Andy</string></value>
661\layout Code
662
663</member>
664\layout Code
665
666</struct></value>
667\layout Code
668
669</member>
670\layout Code
671
672...
673\layout Standard
674
675Unauthorized access attempt returns:
676\layout Code
677
678<methodResponse>
679\layout Code
680
681<params>
682\layout Code
683
684<param>
685\layout Code
686
687<value><string>UNAUTHORIZED</string></value>
688\layout Code
689
690</param>
691\layout Code
692
693</params>
694\layout Code
695
696</methodResponse>
697\layout Section
698
699More to come...
700\layout Standard
701
702Documenting every single call will be difficult, but should be done.
703 In leiu of this, please see the class.bo{APPNAME}.inc.php files in each applicatio
704n/inc directory in the egroupware cvs.
705 In this file will be a list_methods() function, which returns the information
706 to the server about input/output structure for each call.
707 If the file does not have this function, then it is not yet workable via
708 this interface.
709 As for the actual functions, they are also in this file.
710 Generally, they will all accept associative array input and return same,
711 but not always.
712 This code is in flux, have fun.
713\the_end
Note: See TracBrowser for help on using the repository browser.