DokuWiki

It's better when it's simple

User Tools

Site Tools


devel:xmlrpc

XML-RPC

XML-RPC is one of the available protocols to access DokuWiki's Remote API.

The API implements the Wiki RPC Interface 2.0 Specifications (web.archive.org) in the wiki.* namespace and adds additional DokuWiki specific calls in the dokuwiki.* namespace.

Plugins can add their own calls to the API using Remote Plugin components.

Note: there is also a JSON-RPC API which provides the same functionality but is based on JSON rather XML.

Get It Working

  1. Set the remote option to enable XML-RPC in the Configuration Settings “Authentication” section
  2. Set the remoteuser option with a mix of comma separated “usernames,groups”
  3. 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.
  4. 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.
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
Available parameters are:
$params['ow'] = true if file is to overwrite an already
existing media object of the given id.
Data
Description Uploads a file as a given media 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:

NameDescriptionRemote plugins compatible with last two releases
ACL PluginManage page and namespace access control list (ACL) settings (bundled with DokuWiki)1acl
API PluginA plugin that implements a Rest API1api
confmanager PluginPlugin to manage various .conf files1confmanager
doxycode PluginParse code snippets in dokuwiki with cross referencing to doxygen documentation.1doxycode
JSON Data PluginBuild JSON database inside DokuWiki page and use the data in the page1json
struct PluginA new structured data plugin1struct
TagFilter PluginAllows to create custom dropdown fields to easily filter pages based on tags1tagfilter

∑ 7 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.

devel/xmlrpc.txt · Last modified: 2024-01-31 23:57 by Klap-in

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki