[Sommaire] [Imprimer]

   1  eGroupWare XML-RPC/SOAP Methodology
   2  
   3  (C) 2001-2004 Miles Lott
   4  
   5  milos@groupwhere.org
   6  
   7  August 23, 2001 and December 29, 2003
   8  
   9  additions made September 3, 2001.
  10  
  11  This document is very preliminary, but describes a working
  12  system.
  13  
  14  1 System level requests
  15  
  16  1.1 Login and authentication
  17  
  18  Authentication for user logins is handled internally no differently
  19  than for the typical eGroupWare login via web browser. Server
  20  logins, added for XML-RPC and SOAP, are only slightly different.
  21  For either protocol, user and server login and authentication
  22  and subsequent requests are handled by their respective
  23  server apps, xmlrpc.php and soap.php. A server is identified
  24  by a custom HTTP header, without which a normal user login
  25  will be undertaken.
  26  
  27  A client or server sends the appropriate XML-RPC or SOAP
  28  packet containing host, user, and password information to
  29  the egroupware server. The server then assigns a sessionid and
  30  key, which is returned to the client in the appropriate
  31  format.
  32  
  33  Our current method for authenticating requests after successful
  34  login is via the Authorization: Basic HTTP header to be
  35  sent by the client or requesting server. The format of this
  36  header is a base64 encoding of the assigned sessionid and
  37  kp3 variables, seperated by a ':'.
  38  
  39  Further security may be obtained by using SSL on the client
  40  and server. In the future, we may encrypt/decrypt the data
  41  on either end, or at least provide this as an option. The
  42  sessionid and key variables will make this possible, and
  43  relatively secure.
  44  
  45  1.1.1 system.login
  46  
  47  The first request a client will make is the system.login
  48  method. Here is a sample of a server login packet in XML-RPC:
  49  
  50  <?xml version="1.0"?>
  51  <methodCall>
  52  <methodName>system.login</methodName>
  53  <params>
  54  <param>
  55  <value><struct>
  56  <member><name>server_name</name>
  57  <value><string>my.host.name</string></value>
  58  </member>
  59  <member><name>username</name>
  60  <value><string>bubba</string></value>
  61  </member>
  62  <member><name>password</name>
  63  <value><string>gump</string></value>
  64  </member> </struct></value>
  65  </param>
  66  </params>
  67  </methodCall>
  68  
  69  And the same in SOAP:
  70  
  71  <?xml version="1.0"?>
  72  <SOAP-ENV:Envelope
  73  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
  74  xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:xsd="http://www.w3.org/1999/XMLSchema"
  75  xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
  76  xmlns:si="http://soapinterop.org/xsd"
  77  xmlns:ns6="http://soapinterop.org" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  78  <SOAP-ENV:Body> <ns6:system_login>
  79  <server_name xsi:type=":string">my.host.name</server_name>
  80  <username xsi:type=":string">bubba</username>
  81  <password xsi:type=":string">gump</password>
  82  </ns6:system_login>
  83  </SOAP-ENV:Body>
  84  </SOAP-ENV:Envelope>
  85  
  86  The same style of packet would be required for a user/client
  87  login. A successful login should yield the following reply:
  88  
  89  <methodResponse>
  90  <params>
  91  <param>
  92  <value><struct>
  93  <member><name>sessionid</name>
  94  <value><string>cf5c5534307562fc57915608377db007</string></value>
  95  </member>
  96  <member><name>kp3</name>
  97  <value><string>2fe54daa11c8d52116788aa3f93cb70e</string></value>
  98  </member>
  99  </struct></value>
 100  </param>
 101  </params>
 102  </methodResponse>
 103  
 104  And a failed login:
 105  
 106  <methodResponse>
 107  <params>
 108  <param>
 109  <value><struct>
 110  <member><name>GOAWAY</name>
 111  <value><string>XOXO</string></value>
 112  </member>
 113  </struct></value>
 114  </param>
 115  </params>
 116  </methodResponse>
 117  
 118  1.1.2 system.logout
 119  
 120  Logout:
 121  
 122  <?xml version="1.0"?>
 123  <methodCall>
 124  <methodName>system.logout</methodName>
 125  <params> <param>
 126  <value><struct>
 127  <member><name>sessionid</name>
 128  <value><string>ea35cac53d2c12bd05caecd97304478a</string></value>
 129  </member>
 130  <member><name>kp3</name>
 131  <value><string>4f2b256e0da4e7cbbebaac9f1fc8ca4a</string></value>
 132  </member>
 133  </struct></value>
 134  </param>
 135  </params>
 136  </methodCall>
 137  
 138  Logout worked:
 139  
 140  <methodResponse>
 141  <params>
 142  <param>
 143  <value><struct>
 144  <member><name>GOODBYE</name>
 145  <value><string>XOXO</string></value>
 146  </member>
 147  </struct></value>
 148  </param>
 149  </params>
 150  </methodResponse>
 151  
 152  2 Business layer requests
 153  
 154  Once a successful login return packet has been received and
 155  sessionid/kp3 have been extracted, every subsequent packet
 156  sent to the egroupware server must be preceded by an Authorization
 157  header. Here is a sample header:
 158  
 159  POST /egroupware/xmlrpc.php HTTP/1.0
 160  User-Agent: PHP XMLRPC 1.0
 161  Host: my.local.host
 162  Authorization: Basic ZDgxNDIyZDRkYjg5NDEyNGNiMzZlMDhhZTdlYzAxZmY6NTU3YzkyYjBmNGE4ZDVlOTUzMzI2YmU2OTQyNjM3YjQ=
 163  Content-Type: text/xml
 164  Content-Length: 875
 165  
 166  The longish string is a base64 encoding of the $sessionid
 167  . ':' . $kp3. For now this is our only supported authentication
 168  method. Additional methods would probably also affect the
 169  methodCalls. This is certainly open to discussion. Following
 170  is a typical request for some contact data:
 171  
 172  <?xml version="1.0"?>
 173  <methodCall>
 174  <methodName>addressbook.boaddressbook.read_entries</methodName>
 175  <params>
 176  <param>
 177  <value><struct>
 178  <member><name>start</name>
 179  <value><string>1</string></value>
 180  </member>
 181  <member><name>limit</name>
 182  <value><string>5</string></value>
 183  </member>
 184  <member><name>fields</name>
 185  <value><struct>
 186  <member><name>n_given</name>
 187  <value><string>n_given</string></value>
 188  </member>
 189  <member><name>n_family</name>
 190  <value><string>n_family</string></value>
 191  </member>
 192  </struct></value>
 193  </member>
 194  <member><name>query</name>
 195  <value><string></string></value>
 196  </member>
 197  <member><name>filter</name>
 198  <value><string></string></value>
 199  </member>
 200  <member><name>sort</name>
 201  <value><string></string></value>
 202  </member>
 203  <member><name>order</name>
 204  <value><string></string></value>
 205  </member>
 206  </struct></value>
 207  </param>
 208  </params>
 209  </methodCall>
 210  
 211  Successful response:
 212  
 213  <?xml version="1.0"?>
 214  <methodResponse>
 215  <params> 
 216  <param>
 217  <value><struct>
 218  <member><name>0</name>
 219  <value><struct> 
 220  <member><name>id</name>
 221  <value><string>1</string></value>
 222  </member>
 223  <member><name>lid</name>
 224  <value><string></string></value>
 225  </member>
 226  <member><name>tid</name> 
 227  <value><string>n</string></value> 
 228  </member>
 229  <member><name>owner</name> 
 230  <value><string>500</string></value> 
 231  </member>
 232  <member><name>access</name>
 233  <value><string>private</string></value> 
 234  </member>
 235  <member><name>cat_id</name> 
 236  <value><string>1</string></value> 
 237  </member> 
 238  <member><name>n_given</name> 
 239  <value><string>Alan</string></value> 
 240  </member> 
 241  </struct></value> 
 242  </member> 
 243  <member><name>1</name>
 244  <value><struct>
 245  <member><name>id</name>
 246  <value><string>2</string></value>
 247  </member>
 248  <member><name>lid</name>
 249  <value><string></string></value>
 250  </member>
 251  <member><name>tid</name>
 252  <value><string>n</string></value>
 253  </member>
 254  <member><name>owner</name>
 255  <value><string>500</string></value>
 256  </member>
 257  <member><name>access</name>
 258  <value><string>private</string></value>
 259  </member>
 260  <member><name>cat_id</name>
 261  <value><string>1</string></value>
 262  </member>
 263  <member><name>n_given</name>
 264  <value><string>Andy</string></value>
 265  </member>
 266  </struct></value>
 267  </member>
 268  
 269  ...
 270  
 271  Unauthorized access attempt returns:
 272  
 273  <methodResponse>
 274  <params>
 275  <param>
 276  <value><string>UNAUTHORIZED</string></value>
 277  </param>
 278  </params>
 279  </methodResponse>
 280  
 281  3 More to come...
 282  
 283  Documenting every single call will be difficult, but should
 284  be done. In leiu of this, please see the class.bo{APPNAME}.inc.php
 285  files in each application/inc directory in the egroupware
 286  cvs. In this file will be a list_methods() function, which
 287  returns the information to the server about input/output
 288  structure for each call. If the file does not have this
 289  function, then it is not yet workable via this interface.
 290  As for the actual functions, they are also in this file.
 291  Generally, they will all accept associative array input
 292  and return same, but not always. This code is in flux, have
 293  fun.