Table of Contents

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

  1. 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
  2. Enable the XML-RPC in config.php (HINT: $conf['xmlrpc_enable'] = 1)
  3. Setup an XML RPC user in auth.php (HINT: uncomment 'abcd' api_key for testing)
  4. Set the Endpoint URI to your installation: http://yourdomain.com/your_address_book/xmlrpc.php
  5. Choose method: version
  6. As parameters type in your API key (don't forget quotation marks if necessary)
  7. Hit Execute
  8. 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