XML-RPC

experimental

DokuWiki has an experimental XML-RPC API which can be used to access/interact with your wiki from other applications. Up to now the provided API implements the Wiki RPC Interface 2.0 Specifications.

Questions and suggestions to extend and improve the API should be directed to the mailinglist.

1. You need at least the 2008-03-31 release of DokuWiki.
2. Enable the XML-RPC interface in the “Advanced Options” section
3. Set the xmlrpcuser option
4. For security reasons it's safer to allow access to the XML-RPC over HTTPS only. The .htaccess.dist in the development version of DokuWiki contains some rewrite rules to do that.

You can access the XML-RPC interface via the following URL:

http://<your wiki/domain/ip>/lib/exe/xmlrpc.php
https://<your wiki/domain/ip>/lib/exe/xmlrpc.php

Here is an example of how to post to the API:

POST /RPC2 HTTP/1.0
User-Agent: Frontier/5.1.2 (WinNT)
Host: betty.userland.com
Content-Type: text/xml
Content-length: 181

<?xml version="1.0"?>
  <methodCall>
    <methodName>examples.getStateName</methodName>
    <params>
      <param> 
        <value>
          <i4>41</i4>
        </value>
      </param> 
    </params> 
  </methodCall> 

  <?xml version="1.0"?>
    <methodCall>
      <methodName>dokuwiki.getVersion</methodName>
    </methodCall>

Functions are listed in the following format:

This simple example will pull the version information from the given Dokuwiki.

• You need to download and install the library XML-RPC for PHP for this example.
• The URL of the DW-Server must be given without the procotol (http://).

<?php
include('lib/xmlrpc.inc');  // or whereever you habe downloaded and put the XML-RPC for PHP libraries
 
// create a new client instance
$c = new xmlrpc_client('/lib/exe/xmlrpc.php', 'adminwiki.kreisbote.de', 80);
 
// enable debugging to see more infos :-) (well, not for production code)
$c->setDebug(1);
 
// create the XML message to send
$m = new xmlrpcmsg('dokuwiki.getVersion');
 
// send the message and wait for response
$r = $c->send($m);
if($r == false) die('error');
if(!$r->faultCode()){
  // seems good. Now do whatever you want with the data
  $v = php_xmlrpc_decode($r->value());
  echo "$v";
}

Note: DokuWiki has it's own XMLRPC library which could also be used. Some hints how to implement an XMLRPC client with DokuWiki's library can be found by having a look at the sync plugin's source code.

var xml='<?xml version="1.0"?><methodCall><methodName>wiki.getRPCVersionSupported</methodName><params></params></methodCall>';
 $.ajax({
   url: "http://<your wiki>/wiki/lib/exe/xmlrpc.php",
   data: xml,
   contentType:"text/xml",
   type:"post"
 });

This is a small (and not really smart ) sample client implemented in python, just save it to maybe ~/bin/dokuxmlrpc.py and make it executable. You can use it to test the XMLRPC interface, but it's not intended to be useful beyond that . You'll need to install pythons xmlrpclib module in order to use it! You also have to change the settings WIKI, USER and PWD.

dokuxmlrpc.py

#!/usr/bin/env python
# ###################################################################
# @file     ~/bin/dokuxmlrpc.py
# @author   Michael Klier <chi@chimeric.de>
# @modified Jan 25, 2008 19:08:05
#
# utility to query DokuWikis' XMLRPC interface
# ###################################################################
 
__author__ = "Michael Klier"
__version__ = "0.1"
 
# CONFIG
WIKI='WIKIURL'
USER='USERNAME'
PWD='PASSWORD'
 
import sys
import getopt
from urllib import urlencode
 
try:
    import xmlrpclib
except ImportError:
    print "This script needs the xmlrpclib module!"
    sys.exit(1)
 
# prints a hopefully usefull help message
def help():
    print """
NAME
        dokuwikixmlrpc.py - utility to query DokuWiki's XMLRPC interface
 
SYNOPSIS
        dokuxmlrpc.py --help
        dokuxmlrpc.py -h
        dokuxmlrpc.py [option]
 
DESCRIPTION
        dokuxmlrpc.py is a small utility to query DokuWiki's XMLRPC interface.
        It supports all provided callbacks.
 
OPTIONS
        -h or --help
                This options displays this help message.
 
        --backlinks [wikipage]
                Shows a list of links which link to the given wikipage.
 
        --getpage [wikipage]
                Returns the wiki markup of the given wikipage.
 
        --gethtml [wikipage]
                Returns the HTML body of the given wikipage.
 
        --pageinfo [wikipage]
                Shows some information about the given wikipage like author,
                date of last modification a.s.o..
 
        --listpages
                Shows a list of all pages of the wiki.
 
        --listlinks [wikipage]
                Shows a list of all links contained in a given wiki page.
 
        --recent [timestamp]
                Shows a list of changed pages since the given timestamp.
 
        --putpage [wikipage]
                Asks for a wiki text and a summary and saves the given wikipage.
 
AUTHOR
        Michael Klier <chi@chimeric.de>
 
"""
 
## BEGIN MAIN
if __name__ == '__main__':
    url = WIKI + "/lib/exe/xmlrpc.php?" + urlencode({'u':USER,'p':PWD})
    rpc = xmlrpclib.ServerProxy(url)
 
    opts_short = 'h'
    opts_long  = ['help', 'dokuversion', 'backlinks=', 'getpage=', 'gethtml=', 'pageinfo=', 'listpages', 'listlinks=', 'recent=', 'putpage=']
 
    try:
        argv = sys.argv[1:]
        opts, args = getopt.getopt(argv, opts_short, opts_long)
 
        for opt, arg in opts:
 
            try:
 
                if opt in ('-h', '--help'):
                    help()
 
                if opt == '--dokuversion':
                    print rpc.dokuwiki.getVersion()
 
                if opt == '--backlinks':
                    backlinks = rpc.wiki.getBackLinks(arg)
                    for link in backlinks:
                        print link
 
                if opt == '--getpage':
                    print rpc.wiki.getPage(arg)
                    sys.exit(0)
 
                if opt == '--gethtml':
                    print rpc.wiki.getPageHTML(arg)
 
                if opt == '--pageinfo':
                    info = rpc.wiki.getPageInfo(arg)
                    print "name:\t\t", info['name']
                    print "author:\t", info['author']
                    print "lastModified:\t", info['lastModified']
                    print "version:\t", info['version']
 
                if opt == '--listpages':
                    pages = rpc.wiki.getAllPages()
                    for page in pages:
                        print page
 
                if opt == '--listlinks':
                    links = rpc.wiki.listLinks(arg)
                    for link in links:
                        print "type: %(type)s \tpage: %(page)s href: %(href)s" % link
 
                if opt == '--recent':
                    changes = rpc.wiki.getRecentChanges(int(arg))
                    for change in changes:
                        print "last modified: %(lastModified)s author: %(author)s name: %(name)s" % change
 
                if opt == '--putpage':
                    params = {}
 
                    print "insert text to write:"
                    text = sys.stdin.read()
 
                    print "insert summary:"
                    params['sum'] = sys.stdin.read()
 
                    print "insert minor (1)"
                    params['minor'] = sys.stdin.read()
 
                    rpc.wiki.putPage(arg, text, params)
 
                sys.exit(0)
 
            # catch XMLRPC fault
            except xmlrpclib.Fault, err:
                print "dokuxmlrpc.py: %s" % err
                sys.exit(0)
 
    except getopt.GetoptError, err:
        print "dokuxmlrpc.py: %s" % err
        print "Try 'dokuxmlrpc --help' for more information."
        sys.exit(2)
 
# vim:ts=4:sw=4:enc=utf-8: