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

XML-RPC

experimental

DokuWiki has an experimental XML-RPC API which can be used to access/interact with your wiki from other applications. The API implements the Wiki RPC Interface 2.0 Specifications in the wiki.* namespace and adds additional DokuWiki specific calls in the dokuwiki.* namespace. See web services for some general notes about DokuWikis possibilities.

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

Get It Working

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

Accessing The XML-RPC Interface

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

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

or

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

Sample XML Requests

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>

example put page

  <?xml version="1.0"?>
<methodCall>
	<methodName>wiki.putPage</methodName>
	<params>
		<param> 
			<value>
				<string>myputpage  
				</string>
			</value>
		</param> 
		<param> 
			<value>
				<string>======  Devices List ======
Report Created on 2017-05-25 16:23:37
===== Servers =====
^ID ^Name ^Description ^IP ^Type ^OS ^Last Scan ^
|18 |[[:inventory:devices:Computer:adminserver ID-18|adminserver]] |AT/AT COMPATIBLE |192.168.1.1 |Server |Microsoft Windows 2000 Server |2017-05-25 16:09:10 |
 
				</string>
			</value>
		</param>
		<param> 
			<value>
				<struct>
					<member>
						<name>sum</name>
						<value><string>Spiceworks</string></value>
					</member>
					<member>
						<name>minor</name>
						<value><boolean>True</boolean></value>
					</member>
				</struct>
			</value>
		</param> 
	</params> 
</methodCall>

Available Functions

Functions are listed in the following format:

Name The name of the function
Parameters A list of parameters to pass to the function
Data The type of the returned data
Description Short explanation what the function does
Since The DokuWiki (and XML-RPC API Version) this function was introduced

dokuwiki.getPagelist

Name dokuwiki.getPagelist
Parameters (string) namespace, (array) options
Data (array) list of page items
Description Lists all pages within a given namespace. The options are passed directly to search_allpages().
Since 2009-03-06 (1)

dokuwiki.getVersion

Name dokuwiki.getVersion
Parameters -
Data (string) version number
Description Returns the DokuWiki version of the remote Wiki.

dokuwiki.getTime

Name dokuwiki.getTime
Parameters -
Data (int) timestamp
Description Returns the current time at the remote wiki server as Unix timestamp.
Since 2009-03-06 (1)

dokuwiki.getXMLRPCAPIVersion

Name dokuwiki.getXMLRPCAPIVersion
Parameters -
Data (int) version number
Description Returns the XML RPC interface version of the remote Wiki. This is DokuWiki implementation specific and independent of the supported standard API version returned by wiki.getRPCVersionSupported.
Since 2009-03-06 (1)

dokuwiki.login

Name dokuwiki.login
Parameters (string) user, (string) password
Data (boolean) login successful
Description Uses the provided credentials to execute a login and will set cookies. This can be used to make authenticated requests afterwards. Your client needs to support cookie handling. Alternatively use HTTP basic auth credentials.
Since 2009-03-06 (1)

dokuwiki.search

Name dokuwiki.search
Parameters (string) a query string as described on search
Data (array) associative array with matching pages similar to what is returned by dokuwiki.getPagelist, snippets are provided for the first 15 results
Description Performs a fulltext search.
Since 2010-02-28 (3)

dokuwiki.getTitle

Name dokuwiki.getTitle
Parameters -
Data (string) the title of the wiki
Description Returns the title of the wiki.
Since 2010-04-18 (4)

dokuwiki.appendPage

Name dokuwiki.appendPage
Parameters (string) pagename, (string) raw Wiki text, (array) attrs
Where attrs can contain the following:
$attrs['sum'] = (string) change summary
$attrs['minor'] = (boolean) minor
Data (boolean)
Description Appends text to a Wiki Page.
Since 2010-11-20 (5)

dokuwiki.setLocks

Name dokuwiki.setLocks
Parameters (array) list of two lists of page ids
array('lock'=>array(...), 'unlock'=>array(...))
Data (array) array with 4 lists of pageids
array('locked'=>array(...), 'lockfail'=>array(...), 'unlocked'=>array(...), 'unlockfail'=>array(...))
Description Allows you to lock or unlock a whole bunch of pages at once. Useful when you are about to do an operation over multiple pages.
Since 2009-03-06 (1)

wiki.getRPCVersionSupported

Name wiki.getRPCVersionSupported
Parameters -
Data (string) version number
Description Returns 2 with the supported RPC API version.

wiki.aclCheck

Name wiki.aclCheck
Parameters (string) pagename
Data (int) Permissions of given wiki page
Description Returns the permission of the given wikipage.

wiki.getPage

Name wiki.getPage
Parameters (string) pagename
Data (string) raw Wiki text
Description Returns the raw Wiki text for a page.

wiki.getPageVersion

Name wiki.getPageVersion
Parameters (string) pagename, (int) Timestamp
Data (string) raw Wiki text
Description Returns the raw Wiki text for a specific revision of a Wiki page.

wiki.getPageVersions

Name wiki.getPageVersions
Parameters (string) pagename, (int) offset
Data (array) each array item holds the following data:

$data['user'] = username $data['ip'] = ip address $data['type'] = type of change $data['sum'] = summary $data['modified'] =  modification date as IXR_Date Object  $data['version'] = page version as timestamp 
Description Returns the available versions of a Wiki page. The number of pages in the result is controlled via the recent configuration setting. The offset can be used to list earlier versions in the history.

wiki.getPageInfo

Name wiki.getPageInfo
Parameters (string) pagename
Data (array) an array containing the following data:

$data['name'] = [[:pagename]]
$data['lastModified'] = modification date as IXR_Date Object
$data['author'] = author of the Wiki page.
$data['version'] = page version as timestamp
Description Returns information about a Wiki page.

wiki.getPageInfoVersion

Name wiki.getPageInfoVersion
Parameters (string) pagename, (int) timestamp
Data (array) an array containing the following data:

$data['name'] = [[:pagename]]
$data['lastModified'] = modification date as UTC timestamp
$data['author'] = author of the Wiki page.
$data['version'] = page version as timestamp
Description Returns information about a specific version of a Wiki page.

wiki.getPageHTML

Name wiki.getPageHTML
Parameters (string) pagename
Data (string) rendered HTML
Description Returns the rendered XHTML body of a Wiki page.

wiki.getPageHTMLVersion

Name wiki.getPageHTMLVersion
Parameters (string) pagename, (int) timestamp
Data (string) rendered HTML
Description Returns the rendered HTML of a specific version of a Wiki page.

wiki.putPage

Name wiki.putPage
Parameters (string) pagename, (string) raw Wiki text, (array) attrs
Where attrs can contain the following:
$attrs['sum'] = (string) change summary
$attrs['minor'] = (boolean) minor
Data (boolean)
Description Saves a Wiki Page.
Name wiki.listLinks
Parameters (string) pagename
Data (array) each array item holds the following data:

$data['type'] = local/extern
$data['page'] = the wiki page (or the complete URL if extern)
$data['href'] = the complete URL
Description Returns a list of all links contained in a Wiki page.

wiki.getAllPages

Name wiki.getAllPages
Parameters -
Data (array) One item for each page, each item containing the following data:

$data['id'] = id of the page
$data['perms'] = integer denoting the permissions on the page
$data['size'] = size in bytes
$data['lastModified'] = dateTime object of last modification date
Description Returns a list of all Wiki pages in the remote Wiki.
Name wiki.getBackLinks
Parameters (string) pagename
Data (array)
Description Returns a list of backlinks of a Wiki page.

wiki.getRecentChanges

Name wiki.getRecentChanges
Parameters (int) timestamp
Data (array) each array item holds the following data:

$data['name'] = page id
$data['lastModified'] =  modification date as UTC timestamp
$data['author'] = author
$data['version'] = page version as timestamp
Description Returns a list of recent changes since given timestamp.
As stated in recent_changes: Only the most recent change for each page is listed, regardless of how many times that page was changed.

wiki.getRecentMediaChanges

Name wiki.getRecentMediaChanges
Parameters (int) timestamp
Data (array) each array item holds the following data:

$data['name'] = media id
$data['lastModified'] =  modification date as UTC timestamp
$data['author'] = author
$data['version'] = page version as timestamp
$data['perms'] = media permissions
$data['size'] = media size in bytes
Description Returns a list of recent changed media since given timestamp.

wiki.getAttachments

Name wiki.getAttachments
Parameters (String) namespace, (array) options
Data (array) each array item holds the following data:

$data['id'] = media id
$data['file'] = name of the file
$data['size'] = size in bytes
$data['mtime'] = upload date as a timestamp
$data['lastModified'] =  modification date as XML-RPC Date object
$data['isimg'] = true if file is an image, false otherwise
$data['writable'] = true if file is writable, false otherwise
$data['perms'] = permissions of file
Description Returns a list of media files in a given namespace. The options are passed directly to search_media().

wiki.getAttachment

Name wiki.getAttachment
Parameters (String) id
Data (string) the data of the file, encoded in base64
Description Returns the binary data of a media file.

wiki.getAttachmentInfo

Name wiki.getAttachmentInfo
Parameters (String) id
Data (array) an array containing the following information about the file:

$data['size'] = size in bytes
$data['lastModified'] = modification date as XML-RPC Date object
Description Returns information about a media file.

wiki.putAttachment

Name wiki.putAttachment
Parameters (String) id, (base64) data, (array) params
Data
Description Uploads a file as a given media id. Available parameters are:

$params['ow'] = true if file is to overwrite an already existing media object of the given id

.

wiki.deleteAttachment

Name wiki.deleteAttachment
Parameters (String) id
Data
Description Deletes a file. Fails if the file is still referenced from any page in the wiki.

plugin.acl.addAcl

Name plugin.acl.addAcl
Parameters (String) scope, (String) username, (int) permission
Data (boolean) return true if the rule was correctly added
Description Add an ACL rule. Use @groupname instead of user to add an ACL rule for a group.

plugin.acl.delAcl

Name plugin.acl.delAcl
Parameters (String) scope, (String) username
Data (boolean) return true if the rules were correctly deleted
Description Delete any ACL rule matching the given scope and user. Use @groupname instead of user to delete the ACL rules for the group.

Adding methods to the XML-RPC API

Use Remote Plugins to add other methods to the XML-RPC API.

To implement such a plugin please have a look at the remote plugins development documentation.

XML-RPC Error Codes

Since XML-RPC API Version 7 (API Version 7 is since Release Adora Belle (2012-10-13)) useful hierarchical error codes have been introduced. The following error codes can be returned by the XML-RPC Interface:

Italic rows are just categories. Only normal printed rows are returned by the interface.

  • 100 → Page errors
    • 110 → Page access errors
      • 111 → User is not allowed to read the requested page
      • 112 → User is not allowed to edit the page
      • 113 → manager permission is required
      • 114 → superuser permission is required
    • 120 → Page existence errors
      • 121 → The requested page does not exist
    • 130 → Page edit errors
      • 131 → Empty page id
      • 132 → Empty page content
      • 133 → Page is locked
      • 134 → Positive wordblock check
  • 200 → Media errors
    • 210 → Media access errors
      • 211 → User is not allowed to read the requested media
      • 212 → User is not allowed to delete media
      • 215 → User is not allowed to list media
    • 220 → Media existence errors
      • 221 → The requested media does not exist
    • 230 → Media edit errors
      • 231 → Filename not given
      • 232 → File is still referenced
      • 233 → Could not delete file
  • 300 → Search errors
    • 310 → Argument errors
      • 311 → The provided value is not a valid timestamp
    • 320 → Search result errors
      • 321 → No changes in specified timeframe

Additionally there are some server error codes that indicate some kind of server or XML-RPC failure. The codes are the following:

  • -32600 → Invalid XML-RPC request. Not conforming to specification.
  • -32601 → Requested method does not exist.
  • -32602 → Wrong number of parameters or invalid method parameters.
  • -32603 → Not authorized to call the requested method (No login or invalid login data was given).
  • -32604 → Forbidden to call the requested method (but a valid login was given).
  • -32605 → The XML-RPC API has not been enabled in the configuration
  • -32700 → Parse Error. Request not well formed.
  • -32800 → Recursive calls to system.multicall are forbidden.
  • -99999 → Unknown server error.

Sample Java Client

A java client for Dokuwiki is available on github.

Example which displays the title of the wiki and the list of its pages:

import dw.xmlrpc.DokuJClient;
import dw.xmlrpc.Page;
 
public class Main {
  public static void main(String[] args) throws Exception{
    String url = "http://mywiki/lib/exe/xmlrpc.php";
    String user = "myUser";
    String pwd = "myPassword";
 
    DokuJClient client = new DokuJClient(url, user, pwd);
    System.out.println("Pages in the wiki " + client.getTitle() + " are:");
    for(Page page : client.getAllPages()){
      System.out.println(page.id());
    }
 
  }
}

Sample PHP Client

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 have 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";
}
<?php
include('/lib/xmlrpc.inc');
 
$c = new xmlrpc_client('/lib/exe/xmlrpc.php', 'localhost', 80);
$c->setDebug = 1;
 
$m = new xmlrpcmsg('wiki.putAttachment');
$m->addParam(new xmlrpcval("file.png", "string"));
$m->addParam(new xmlrpcval("iVBORw0KGgoAAAANSUhEUgAAADAAAAAwC.....<base64 string here>...", "base64"));
$m->addParam(new xmlrpcval(array("ow" => new xmlrpcval(true, "boolean")), "struct"));
 
$r = $c->send($m);
if($r == false) die('foo!');
 
// Output the response object
// var_dump($r);
$r = $c->send($m);
 
if(!$r->faultCode()) {
    $v = php_xmlrpc_decode($r->value());
    echo $v;
} else {
    echo $r->faultString();
}
 
?>

DokuWiki has its own XML-RPC library which could also be used. A simple client using that library looks like this:

<?php
require_once('inc/init.php');
 
$client = new IXR_Client('http://localhost/devel/dokuwiki/lib/exe/xmlrpc.php');
$client->debug = 1; // enable for debugging
$client->query('dokuwiki.login','admin','pass');
$ok = $client->getResponse();
if($ok) {
   $client->query('wiki.getPage','wiki:syntax');
   echo $client->getResponse();
}

Sample Perl Client

Dokuwiki::RPC::XML::Client is simple dokuwiki client written on top of RPC::XML::Client, it comes with a CLI command you can use from shell.

you can also write RPC::XML::Client code directly following this simple example will pull the version information and the list of documents in the wiki namespace from the given Dokuwiki. It also lists all .png mediafiles from the same namespace and its child namespaces.

use strict;
use warnings;
use feature 'say';
use RPC::XML::Client;
use Data::Dumper;
 
my $client =
  RPC::XML::Client->new('https://www.example.com/wiki/lib/exe/xmlrpc.php');
 
my $res = $client->send_request('dokuwiki.getVersion');
say 'dokuwiki.getVersion = ' . $res->value;
 
my $namespace = 'wiki';
my $req =
  RPC::XML::request->new( 'dokuwiki.getPagelist',
    RPC::XML::string->new($namespace),
    RPC::XML::struct->new() );
$res = $client->send_request($req);
say "dokuwiki.getPagelist = \n" . Dumper $res->value;
 
 
# if given and >0 'depth' is relative to the searched namespace and is a maximum.
# setting 'hash' to 1 will put extra load on server.
$res = $client->send_request(
	RPC::XML::request->new( 'wiki.getAttachments',
		RPC::XML::string->new('$namespace'),
		RPC::XML::struct->new( {depth => 2, skipacl => 1, hash => 0, pattern => '/\.png$/' } )
	)
);
say "wiki.getAttachments = \n" . Dumper $res->value;

Sample Ruby Client

This simple example will pull the version information from the given Dokuwiki. No plugin required (in the Windows default package).

require "xmlrpc/client"
server = XMLRPC::Client.new( "localhost","/dokuwiki/lib/exe/xmlrpc.php")
begin
    puts server.call("dokuwiki.getVersion")
rescue XMLRPC::FaultException => e
    puts "Error:"
    puts e.faultCode
    puts e.faultString
end

This example demonstrates how to upload attachments:

require "xmlrpc/client"
server = XMLRPC::Client.new( "localhost","/dokuwiki/lib/exe/xmlrpc.php")
begin
    puts server.call("wiki.putAttachment", "wiki/example.png", XMLRPC::Base64.new(IO.read("/path/to/example.png")))
rescue XMLRPC::FaultException => e
    puts "Error:"
    puts e.faultCode
    puts e.faultString
end

Sample jQuery Client

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",
   beforeSend: function (xhr) {
     xhr.setRequestHeader ("Authorization", "Basic " + btoa('username' + ":" + 'password'));
   },
 });

Python Module

A Python module for DokuWiki's XML-RPC API can be found at the Python package index and on GitHub.

Alternative: python-dokuwiki

Sample AutoIt3 Client

My AutoIt3 client is mainly a proof of concept:

#cs ----------------------------------------------------------------------------
 
 AutoIt Version: 3.2.12.1
 Author:         Hugo Bossard
 
 Script Function:
    XML-RPC sample client AutoIt3 script.
 
#ce ----------------------------------------------------------------------------
 
; this script uses the UDF WinHttp
#include "WinHTTP.au3"
 
; get the info from page 'wiki:syntax' using wiki.getPageInfo()
$Xml = '<?xml version="1.0"?>' 
$Xml = $Xml  & @CRLF & '<methodCall>'
$Xml = $Xml  & @CRLF & '<methodName>wiki.getPageInfo</methodName>'
$Xml = $Xml  & @CRLF & '<params>'
$Xml = $Xml  & @CRLF & '<param>' 
$Xml = $Xml  & @CRLF & '<value>'
$Xml = $Xml  & @CRLF & '<string>wiki:syntax</string>'
$Xml = $Xml  & @CRLF & '</value>'
$Xml = $Xml  & @CRLF & '</param>' 
$Xml = $Xml  & @CRLF & '</params>' 
$Xml = $Xml  & @CRLF & '</methodCall>'
$XmlSize = StringLen($Xml)
 
; initializes the use of WinHTTP functions and returns a WinHTTP-session handle.
$hw_open = _WinHttpOpen()
 
; creates a HTTP request handle to a lokal DokuWikiStick installation on port 8800
$hw_connect = _WinHttpConnect($hw_open, "localhost", 8800)
 
; creates a HTTP request handle
$h_openRequest = _WinHttpOpenRequest($hw_connect, "POST", "/lib/exe/xmlrpc.php", "/RPC2 HTTP/1.0", "localhost", "text/xml")
 
; sends the specified request to the HTTP server
_WinHttpSendRequest($h_openRequest, "", $Xml, $XmlSize)
 
; waits to receive the response to a HTTP request initiated by WinHttpSendRequest().
_WinHttpReceiveResponse($h_openRequest)
 
$Data = ""
Do
  ; reads data from a handle opened by the _WinHttpOpenRequest() function.
  $Data&=_WinHttpReadData($h_openRequest)
Until @error
 
; close connection and clean up
_WinHttpCloseHandle($h_openRequest)
_WinHttpCloseHandle($hw_connect)
_WinHttpCloseHandle($hw_open)
 
; show error number and resulting data
MsgBox(4096,"Error: " & @error, $Data)

Sample Emacs Lisp Client

(require 'xml-rpc)
(defvar *dokuwiki-xml-rpc-url* "https://dokuwiki.url/lib/exe/xmlrpc.php")
(xml-rpc-method-call
  *dokuwiki-xml-rpc-url*
  'dokuwiki.getTime)
devel/xmlrpc.txt · Last modified: 2017-06-15 08:20 by werner.flamme