========================================
 Replacing APIs with your own solutions
========================================

Horde applications are loosely coupled with each other through the application APIs. Each application provides a set of external API methods that can be called from other Horde applications through the Horde Registry, or even externally through the Horde RPC interfaces. See the `Registry wiki page`_ for details.

.. _`Registry wiki page`: https://wiki.horde.org/Doc/Dev/Registry?referrer=CustomizeApis

If you want to provide some functionality through your own or some external code, all you need to do it to register you own code in the Horde Registry and provide the required API methods. For example, if you have your own address book or CRM solution, you could replace Horde's address book module Turba with that program.

Here is a real world example. Say we have a CRM system that is providing contacts. First create a small application stub, a Horde mini-application. We call it "crm" and need the following 3 files to become a working Horde module:

::

 horde/config/registry.d/crm.php
 horde/crm/config/conf.php
 horde/crm/lib/api.php

The registry.d/ directory exists since Horde 3.2. For earlier versions, add the code from crm.php directly to horde/config/registry.php. The directory in newer versions is more flexible since you can update the registry.php configuration file more easily when upgrading to newer Horde versions if you didn't customize it. The name of the file in registry.d is arbitrary. For changes to a file in registry.d/ to take effect, a user must log out and in again. Amendments to registry.php or registry.local.php are effective immediately.

The conf.php can be empty. The registry.d/crm.php file looks like:

::

 <?php
 $this->applications['crm'] = array(
     'fileroot' => dirname(__FILE__) . '/../../crm',
     'webroot' => $this->applications['horde']['webroot'] . '/crm',
     'name' => 'CRM',
     'status' => 'notoolbar',
     'provides' => array('contacts'),
 );

This entry registers an application called "crm" at the Horde Registry, hides it from the toolbar (we only want to use it internally, i.e. it doesn't have a UI), and propagates the "contacts" API. This means that all methods calls to the contacts API will be delegated to the crm module. Turba provides a **lot** of methods through the contacts API, just take a look at turba/lib/api.php to get an impression. You don't have to implement all these methods in your crm module though, because a) not all methods are used in all Horde modules (see below), and b) you can also tell the registry to only provide certain methods of the contacts API. To achieve that, change the 'provides' entry to a less generic value:

::

 'provides' => array('contacts/search', 'contacts/show'),

This tells the Registry that your are only providing the "search" and "show" methods of the "contacts" API. The other methods may be provided by other modules, by Turba, or not at all. 'provides' entries with method names take precedence over generic entries, i.e. if for Turba you have 'provides' => array('contacts') in the registry configuration and 'provides' => array('contacts/search', 'contacts/show') for your own module, than these two method will be routed to your module, all other "contacts/" calls will be delegated to Turba.

The Api.php file finally provides the actual method definitions. At least for Horde5+ it is no longer necessary to include method signatures. The file implements a class that offers the registered services:

::

 <?php
 /**
  * CRM external API interface.
  *
  * This file defines CRM's external Horde API interface. Other Horde
  * applications will interact with CRM through this API.
  */
 
 class CRM_Api extends Horde_Registry_Api
 {
         public function search($args = array(), $type)
         {
                 // do something
         }
         public function show($args = array())
         {
                 // do something
         }
 
 }
 

It's a good idea to start with the function definitions already provided through existing Horde modules, to get some impression which functionality exactly is expected, how returned or incoming data structures look like, and how to deal with errors.

--------------------------------------------------
 API methods called from the several applications
--------------------------------------------------

This section is going to build a list of all Horde applications and the API methods they call. With this list you could easily see which methods you might have to implement if want your application to work with a certain set of Horde modules. Please remember, you don't **have to** implement all methods. If a method doesn't exist, the functionality simply isn't available in the Horde module that would call it.

Of course, you can provide additional API services or functions that may be used outside the Horde framework, i.e. by another Horde application.

Horde
=====

'*/browse'
'*/changeLanguage'
'*/delete'
'*/getActionTimestamp'
'*/import'
'*/list'
'*/listAlarms'
'*/listBy'
'*/listTagInfo'
'*/removeUserData'
'*/replace'
'*/shareHelp'
'clients/clientFields'
'clients/fields'
'clients/getClientSource'
'contacts/import'
'contacts/sources'
'forwards/summary'
'horde/admin_list'
'images/listGalleries'
'images/listImages'
'images/searchTags'
'mail/compose'
'news/searchTags'
'sms/compose'
'telephony/dial'
'tickets/addTicket'
'vacation/summary'

Chora
=====

DIMP
====

Forwards
========

IMP
===

'calendar/delete'
'calendar/eventFromGUID'
'calendar/getFreeBusy'
'calendar/import'
'calendar/import_vfreebusy'
'calendar/show'
'calendar/updateAttendee'
'contacts/add'
'contacts/fields'
'contacts/getField'
'contacts/import'
'contacts/search'
'contacts/show'
'contacts/sources'
'files/returnFromSelectlist'
'files/selectlistResults'
'images/saveImage'
'images/selectGalleries'
'mail/canApplyFilters'
'mail/showBlacklist'
'mail/showFilters'
'mail/showWhitelist'
'notes/import'
'notes/listNotepads'
'notes/show'
'tasks/import'
'tasks/listTasklists'
'tasks/show'

Ingo
====

Jeta
====

Kronolith
=========

MIMP
====

Mnemo
=====

Nag
===

Passwd
======

Turba
=====

Vacation
========