docs:xmlrpc [PHP iAddressBook]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.

====== XML-RPC API Documentation ======


===== Overview =====

As of version 1.0 the iAddressBook comes with an XML-RPC API interface that
allows to integrate the addressbook into other tools. The interface is
intended primarily for querying and syncing the addressbook. The current
design tries to minimize troubles with future interface changes. The most
basic function provided tells you the version number of the interface itself.
This should make it easy to detect different interface layouts in the future
(in case anything should change substantially).

===== Getting Started =====
{{ :docs:xmlrpc_example.png?nolink&500|}}

  - Download an XML-RPC Client such as this one here: http://www.ditchnet.org/xmlrpc/ or use the example python script provided here https://svn.code.sf.net/p/iaddressbook/code/trunk/docs/xmlrpc.py
  - Enable the XML-RPC in config.php (HINT: ''$conf['xmlrpc_enable'] = 1'')
  - Setup an XML RPC user in auth.php (HINT: uncomment 'abcd' api_key for testing)
  - Set the Endpoint URI to your installation: http://yourdomain.com/your_address_book/xmlrpc.php
  - Choose method: ''version''
  - As parameters type in your API key (don't forget quotation marks if necessary)
  - Hit Execute
  - If everything worked you should see an object response similar to the one below

<code>
{
    result = "2.0\n";
    status = success;
}
</code>

===== Authentication and Security =====

The XML-RPC API uses the same authentication mechanism as the generic
web interface. Insted of username and password a unique key is used
for authentication: the //API Key//. Every tool that want to access
the XML-RPC API needs its own personal key. You can setup the keys
in conf/auth.php. Permission can be set on function level and per
//API Key//. This means that you can restrict a specific key to certain
functions of the XML-RPC API. The API has its own functions to separate
the API from the standard web functions in the addressbook.The setup is
almost identical with the setup of web users. The //API Key// has to be
provided with every function call to the XML-RPC API. 

===== Basics for Remote Method Calls =====

Every function takes at least one argument: the //api_key//.
The return values differ from function to function but they
all share a common structure. The return value is alway
a struct with the following two/three members:

^ Key    ^ Type   ^ Values         ^ Description ^
| status | string | success, error | Status contains "success" if the function could be executed successfully and "error" otherwise |
| result | mixed  | - | This is the actual result of the function. In case of error this field remains empty |
| errmsg | string | - | Contains a human readable error message in case of error. This key is not set in case of success |


===== Available Methods =====

^ Method Name     ^ Parameters ^ Return value ^ Description ^
| system.listMethods     | | array of available methods | Returns all supported methods by iAddressBook XMLRPC |
| system.methodSignature | method | signature of method | Returns the method signature for the specified method |
| system.methodHelp      | method | help string of method | Returns the Parameters and return values for the given method |
| version         | api_key    | version string | Returns the iAddressBook version (i.e. "1.0") |
| get_contact     | api_key, contact id    | contact | Returns the contact with the given id |
| get_contacts    | api_key, search string, limit, offset  | contacts | Returns contacts that match search string (or all if string is empty) starting from offset (max. limit contacts) |
| set_contact     | api_key, contact  | contact id | Adds or modifies a contact, returns insert id |
| count_contacts  | api_key, search string  | number of id's | Returns the number of contacts that match the search string |
| delete_contact  | api_key, contact id  | success or error | Deletes the contact with the given id, returns success or error |
| import_vcard    | api_key, vcard as string | success or error | Imports a vCard into the addressbook, returns success or error |
| export_vcard    | api_key, contact id's | vcards as string | Exports all contacts matching the id's as one vCard string |