====== XML-RPC ====== XML-RPC is one of the available protocols to access DokuWiki's [[Remote API]]. The API implements the [[http://www.jspwiki.org/wiki/WikiRPCInterface2|Wiki RPC Interface 2.0 Specifications]] ([[https://web.archive.org/web/20130526043929/http://www.jspwiki.org/wiki/WikiRPCInterface2|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 [[devel:remote_plugins|Remote Plugin components]]. Note: there is also a [[jsonrpc|JSON-RPC]] API which provides the same functionality but is based on JSON rather XML. ===== Get It Working ===== - Set the [[config:remote]] option to enable XML-RPC in the Configuration Settings "Authentication" section - Set the [[config: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:///lib/exe/xmlrpc.php or https:///lib/exe/xmlrpc.php Here are some [[devel:xmlrpc:clients|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 examples.getStateName 41 dokuwiki.getVersion example put page wiki.putPage myputpage This is my page content sum Spiceworks minor True ===== 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 [[xref>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 [[#xml-rpc_error_codes|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 [[:config: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 ==== ^ 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 [[xref>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 [[plugintype>64#extension__table|Remote Plugins]] to add other methods to the XML-RPC API. A summary of recent plugins which indicate Remote support: ---- pluginquery ----- SELECT: name, description WHERE: (type > ? AND type < ?) and (bestcompatible LIKE ? OR bestcompatible LIKE ? OR compatible = ?) VALUES: 63, 128, @DATEMOSTRECENT@, @DATESECONDMOSTRECENT@, (bundled) headline: Remote plugins compatible with last two releases ----- To implement such a plugin please have a look at the [[remote plugins|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 [[devel:xmlrpc:clients|clients written in different languages]] are available.