This is an old revision of the document!
Table of Contents
Adding custom web services
If you want to add an other web-service like REST, JSON-RPC, SOAP, … additional to the existing XML-RPC you can use the RemoteAPI. You just have to develop the transportation layer and don't need to bother with the business logic.
Calling business logic
When writing a new remote interface, you just have to receive the call and get the method name and parameters out of it. With these two information you call the RemoteAPI abstraction layer within a single call. It will return a primitive value. You have to encode these value and send it to the caller.
i.e.
<?php // get the api $remote = new RemoteAPI(); // Parse the incoming call // call the business logic $result = $remote->call('dokuwiki.getVersion'); // or with parameters $result = $remote->call('wiki.deleteAttachment', array('anImage.jpg'));
The call method
The call method takes the method name to call as first parameter. The second parameter is an array with the parameters in the correct order. The default value of the second argument is array().
When something goes wrong - exceptions
In some cases an error occurs while doing the business logic. Then an instance of RemoteException is thrown. This must be handled by the transportation layer. A special case is the RemoteAccessDeniedException. It is thrown when the user has insufficient permissions for the given method.
All exceptions will have an error code and an error message you should return to to caller.
Special return values
Sometimes you want do encode files or dates in a special way before you transport it. Unfortunately there is nothing like a primitive date or file datatype. But you can write a simple transformation method and give the callback to the api.
The methods are:
- setDateTransformation()
- setFileTransformation()
Information about available methods to call
To get more detailed information about the methods you can use the following methods:
- getMethods()
- getCoreMethods()
These methods return an array with information about the existing methods, parameters, return types and maybe a documentation string. An example can be found in inc/RemoteAPICore.php
array( 'dokuwiki.getVersion' => array( 'args' => array(), 'return' => 'string', 'doc' => 'Returns the running DokuWiki version.' ), 'dokuwiki.login' => array( 'args' => array('string', 'string'), 'return' => 'int', 'doc' => 'Tries to login with the given credentials and sets auth cookies.', 'public' => '1' ), 'dokuwiki.getPagelist' => array( 'args' => array('string', 'array'), 'return' => 'array', 'doc' => 'List all pages within the given namespace.', 'name' => 'readNamespace' ) )