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.

1. You need at least the 2008-03-31 release of DokuWiki.
2. Enable the XML-RPC interface in the “Advanced Options” section
3. 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:

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.

#!/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:

How about authentication? I'm hacking together a small application which will allow me to insert pages into my wiki from my Workstation (more on that later) but how can I be sure that no one else is modifying my files? – Mike (x@xarumanx.net - 08/04/09 - 16:48)

Don't bother, I just found out that reading the page does really help…

Just as clarification, the XMLRPC interface is aware of authentication (basic http auth, though I'd recommend to always use https if possible) and DokuWiki's ACL feature. — Michael Klier 2008/04/09 23:31

How about image (and file) upload ? — Aurélien Bompard 2008/05/07 16:44

That's not implemented yet, but it's planned. — Michael Klier 2008/05/07 17:36

That's now possible in the development version! — Michael Klier 2008/07/20 17:04

What about including the page size in wiki.getAllPages? It would be useful to display pages in a directory and some editors use the size of a file to know how much to read. Another thing are permissions, but this is already discussed on the mailinglist. When opening a page it would be nice to know the actual, sanitized pagename (e.g. to use an efficient cache structure or recognize pages that are already open). — Michael Hamann 2008/05/29 22:26

A method that takes raw wiki text and returns HTML without storing it in an actual page would be very nice (as SvenDowideit proposed years ago on the JSPWiki XML RPC Page). DokuWiki has the best parser and syntax extensibility of all wiki engines I've used and it would be great if it could be used without the whole backend for user management and display. So the basic Idea is:

wiki.RawWikiToHTML

That doesn't mean DokuWiki isn't in itself a great application, it just would be nice to easily integrate it's parsing and rendering abilities into some other framework (e.g. Rails, Catalyst or Django). Then one can concentrate on the actual functionality and leave the hard part, parsing, lexing, rendering that is, to something that knows what it's doing (DokuWiki).

I think such a feature would be useful for other cases, too, e.g. I thought about the possibility to implement an editor that displays a preview of the changed content so there would be a need for that function, too.