Differences

This shows you the differences between two versions of the page.

--- devel:custom_webservices [2013-01-23 01:50] – [Special return values] Klap-in
+++ devel:custom_webservices [2024-01-10 15:13] (current) – replaced by devel:remote_api#extending_the_api andi
@@ Line 1: / Line 1: @@
-====== Adding custom web services ======
-If you want to add an other web-service like REST, JSON-RPC, SOAP, ... additional to the existing [[devel:xmlrpc|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.
-<code php>
-<?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'));
-</code>
-==== 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 as 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()
-  * [[remote plugins|getPluginMethods()]]
-  * 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 [[xref>inc/RemoteAPICore.php]]
-<code 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'
-    )
-)
-</code>