DokuWiki

It's better when it's simple

User Tools

Site Tools


Sidebar

Translations of this page?:

Learn about DokuWiki

Advanced Use

Corporate Use

Our Community


Follow us on Facebook, Twitter and other social networks.

devel:custom_webservices

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 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:

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'
    )
)
devel/custom_webservices.txt · Last modified: 2013-01-23 01:50 by Klap-in