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
- 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
{
result = "2.0\n";
status = success;
}
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 |