splitbrain/dokuwiki — pull request #87 by dom-mel (2012-03-14 12:39:04+00:00)
Title: added abstraction layer to xml-rpc api

Rewrite of Dokuwiki XML-RPC Api
=========================

Abstract
------------

This pull request adds an abstraction layer between a RCP implementation, like Rest or XML-RPC, and the business logic of dokuwiki or it's plugins plugins. This idea is suggested on http://www.dokuwiki.org/devel:ideas:remote_api.

What is done?
---------------------

The business logic from lib/exe/xmlrpc.php is moved to inc/RemoteAPICore.php. The description of methods, parameters and return values is refactored and also moved into this file. Calls to the IXR library used for XML-RPC are removed from the business logic. In detail IXR_Errors are now RemoteExceptions, date and file transformations are done via the abstraction layer. Transformations from basic types like string, int, etc. must be handled in a RPC implementation.

The abstraction layer can be found in inc/remote.php. It provides information to RPC interfaces and start the method calls in dokuwiki.

The config option to enable/disable rpc interface is refactored from xmlrpc to remote. It's behavior is the same as the old one. But it's now handled in the abstraction layer.

The IXR library was changed to provide the XMLRPC_CALLBACK_REGISTER	event. This has been removed. It's not documented on dokuwiki.org or used by other plugins according to http://www.dokuwiki.org/devel:plugin_survey:events.

How dose this affect applications that use XML-RPC?
----------------------------------------------------------------------------

The XML-RPC interface looks still the same. Nothing has changed on calling the methods.

How do i add new XML-RPC methods?
--------------------------------------------------------

In dokuwiki core you simply add a method to inc/RemoteAPICore.php and the method description to the array at the top. The style of these information can be found at inc/remote.php.

In a plugin you create a file in lib/plugins//remote.php.
In it you have a structure like that:

``` PHP
array(
'args' => array(),
'return' => 'date'
)
);
}

function getTime() {
return $this->getApi()->toDate(time());
}
}
```

You see nearly the same method information structure. It's just a little bit flatter. A call to the time method via RPC looks like this: plugin.time.getTime - abstract spoken plugin..

How to add a new RPC interface?
------------------------------------------------

New RPC interfaces have to handle all transaction tasks. They have to extract method name and arguments from the call. This is passed to the abstraction layer. It will return mixed data. The RPC has to transform this and transport it to the sender.

In the simplest case there will be only one call to the abstraction layer:
``` PHP
call($methodname, $args);
// transform result
} catch (RemoteException $e) {
// handle error, error message is in $e->getMessage() and error number is in $e->getCode().
}
```

When you need to transform file content and date content you can provide transformation functions to the abstraction layer. An example can be found in lib/exe/xmlrpc.php

Finally
---------
I hope this changes will help to make it easier to use and maintain the remote interface of dokuwiki. I thing there can be more improvements, like a more fine access control. The ACL plugin also could use this new feature to provide ACL methods via RPC.