This is an old revision of the document!
Table of Contents
XML-RPC
DokuWiki has a 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.
Plugins can add their own calls to the API using Remote Plugin components.
Questions and suggestions to extend and improve the API should be directed to the mailinglist.
Get It Working
- You need at least the 2008-03-31 release of DokuWiki.
- Set the remote option to enable XML-RPC in the Configuration Settings “Authentication” section
- Set the remoteuser option with a mix of comma separated “usernames,groups”
- 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. - You might need to install an XML package like
php-xml
(on debian)
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
Here are some Samples of Clients using the XML-RPC Api to test with
Sample XML Requests
You should use an XML-RPC library instead of hand-crafting your 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>This is my page content</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 [ 'lock' => [...], 'unlock' => [...] ] |
Data | (array) array with 4 lists of pageids [ 'locked' => [...], 'lockfail' => [...], 'unlocked' => [...], 'unlockfail' => [...] ] |
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) |
dokuwiki.createUser
Name | dokuwiki.createUser |
---|---|
Parameters | (array) parameters, where parameters can contain: $params = [ 'user' => 'username', 'password' => 'password1', 'name' => 'User Name', 'mail' => 'user@example.com', 'groups' => [ 'user', 'test' ], 'notify' => false ] |
Data | (bool) true if the user is created |
Description | Create a user. Returns 400 range error codes if input is not accepted. |
Since | 2022-06-24 |
dokuwiki.deleteUsers
Name | dokuwiki.deleteUsers |
---|---|
Parameters | (array) list of usernames to delete |
Data | (bool) true if the users were deleted |
Description | Allows you to delete one or more users. Useful to implement GDPR right to be forgotten tools. |
Since | 2018-05-24 |
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. |
wiki.listLinks
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. |
wiki.getBackLinks
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.listAcls
Name | plugin.acl.listAcls |
---|---|
Parameters | - |
Data | (array) of ACLs {scope, user, permission}' |
Description | Get the list of all ACLs. |
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.
A summary of recent plugins which indicate Remote support:
Name | Description | Plugins WHERE (type > 63 AND type < 128) and (compatible LIKE %Hogfather% OR compatible LIKE %Greebo% OR compatible = (bundled)) | |
---|---|---|---|
ACL Plugin | Manage page and namespace access control list (ACL) settings (bundled with DokuWiki) | 1 | acl |
confmanager Plugin | Plugin to manage various .conf files | 1 | confmanager |
JSON Data Plugin | Build JSON database inside DokuWiki page and use the data in the page | 1 | json |
struct Plugin | A new structured data plugin | 1 | struct |
TagFilter Plugin | Allows to create custom dropdown fields to easily filter pages based on tags | 1 | tagfilter |
xcom Plugin | An xmlrpc cross-communication facility that enables two wikis to interact by means of a dashboard interface, including administration, importing of pages and media, and editing on the remote wiki | 1 | xcom |
∑ 6 plugins matching query
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
- 400 → User management errors
- 401 invalid user name given
- 402 invalid user name given
- 403 invalid email address given
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 Clients
A number of clients written in different languages are available.