devel:xmlrpc
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
devel:xmlrpc [2015-04-01 11:18] – [Sample XML Requests] 81.174.162.206 | devel:xmlrpc [2024-01-31 23:57] (current) – [Adding methods to the XML-RPC API] Klap-in | ||
---|---|---|---|
Line 1: | Line 1: | ||
====== XML-RPC ====== | ====== XML-RPC ====== | ||
- | [[: | ||
- | DokuWiki has an experimental [[wp>XML-RPC]] API which can be used to access/interact with your wiki from other applications. The API implements the [[http:// | + | XML-RPC |
+ | |||
+ | |||
+ | The API implements the [[http:// | ||
+ | |||
+ | Plugins can add their own calls to the API using [[devel: | ||
+ | |||
+ | Note: there is also a [[jsonrpc|JSON-RPC]] API which provides the same functionality but is based on JSON rather XML. | ||
- | Questions and suggestions to extend and improve the API should be directed to the [[: | ||
===== Get It Working ===== | ===== Get It Working ===== | ||
- | - You need at least the 2008-03-31 release of DokuWiki. | + | |
- | - Enable | + | - Set the [[config: |
- | - Set the [[config: | + | - Set the [[config: |
- For security reasons it's safer to allow access to the XML-RPC over HTTPS only. DokuWiki' | - For security reasons it's safer to allow access to the XML-RPC over HTTPS only. DokuWiki' | ||
+ | - You might need to install an XML package like '' | ||
+ | |||
===== Accessing The XML-RPC Interface ===== | ===== Accessing The XML-RPC Interface ===== | ||
- | You can access the XML-RPC interface via the following | + | You can access the XML-RPC interface via the following |
http://< | http://< | ||
+ | or | ||
https://< | https://< | ||
+ | |||
+ | Here are some [[devel: | ||
+ | |||
===== Sample XML Requests ===== | ===== 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: | Here is an example of how to post to the API: | ||
+ | |||
+ | |||
<code xml> | <code xml> | ||
POST /RPC2 HTTP/1.0 | POST /RPC2 HTTP/1.0 | ||
Line 27: | Line 44: | ||
<?xml version=" | <?xml version=" | ||
- | | + | < |
< | < | ||
< | < | ||
- | | + | |
- | < | + | < |
- | < | + | < |
- | </ | + | </ |
- | </ | + | </ |
</ | </ | ||
- | | + | </ |
</ | </ | ||
- | < | + | < |
- | <?xml version=" | + | <?xml version=" |
- | < | + | < |
- | < | + | < |
- | </ | + | </ |
+ | </ | ||
+ | |||
+ | example put page | ||
+ | |||
+ | <code xml> | ||
+ | <?xml version=" | ||
+ | < | ||
+ | | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </ | ||
+ | </ | ||
+ | </ | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </ | ||
+ | </ | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </ | ||
+ | < | ||
+ | < | ||
+ | < | ||
+ | </ | ||
+ | </ | ||
+ | </ | ||
+ | </ | ||
+ | </ | ||
+ | </ | ||
</ | </ | ||
===== Available Functions ===== | ===== Available Functions ===== | ||
Functions are listed in the following format: | Functions are listed in the following format: | ||
- | ^ Name | The name of the function | | + | ^ Name |
- | ^ Parameters | + | ^ Parameters |
- | ^ Data | The type of the returned data | | + | ^ Data |
- | ^ Description | Short explanation what the function does | | + | ^ Description |
- | ^ Since | + | ^ Since | The DokuWiki (and XML-RPC API Version) this function was introduced |
==== dokuwiki.getPagelist ==== | ==== dokuwiki.getPagelist ==== | ||
Line 71: | Line 124: | ||
^ Parameters | ^ Parameters | ||
^ Data | (int) timestamp | | ^ Data | (int) timestamp | | ||
- | ^ Description | Returns the current time at the remote wiki server as Unix timestamp | | + | ^ Description | Returns the current time at the remote wiki server as Unix timestamp. | |
^ Since | 2009-03-06 (1) | | ^ Since | 2009-03-06 (1) | | ||
Line 78: | Line 131: | ||
^ Parameters | ^ Parameters | ||
^ Data | (int) version number | | ^ 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 | | + | ^ 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) | | ^ Since | 2009-03-06 (1) | | ||
Line 92: | Line 145: | ||
^ Parameters | ^ Parameters | ||
^ Data | (array) associative array with matching pages similar to what is returned by '' | ^ Data | (array) associative array with matching pages similar to what is returned by '' | ||
- | ^ Description | Performs a fulltext search | | + | ^ Description | Performs a fulltext search. | |
^ Since | 2010-02-28 (3) | | ^ Since | 2010-02-28 (3) | | ||
Line 100: | Line 153: | ||
^ Parameters | ^ Parameters | ||
^ Data | (string) the title of the wiki | | ^ Data | (string) the title of the wiki | | ||
- | ^ Description | Returns the title of the wiki | | + | ^ Description | Returns the title of the wiki. | |
^ Since | 2010-04-18 (4) | | ^ Since | 2010-04-18 (4) | | ||
Line 115: | Line 168: | ||
^ Name | '' | ^ Name | '' | ||
- | ^ Parameters | + | ^ Parameters |
- | ^ Data | (array) array with 4 lists of pageids < | + | |
- | ^ 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 | | + | |
+ | ]</ | ||
+ | ^ Data | (array) array with 4 lists of pageids < | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | ]</ | ||
+ | ^ 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) | | ^ Since | 2009-03-06 (1) | | ||
+ | |||
+ | ==== dokuwiki.createUser ==== | ||
+ | |||
+ | ^ Name | '' | ||
+ | ^ Parameters | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ], | ||
+ | ' | ||
+ | ]</ | ||
+ | ^ Data | (bool) true if the user is created | | ||
+ | ^ Description | Create a user. Returns 400 range [[# | ||
+ | ^ Since | 2022-06-24 | | ||
+ | |||
+ | |||
+ | ==== dokuwiki.deleteUsers ==== | ||
+ | |||
+ | ^ Name | '' | ||
+ | ^ Parameters | ||
+ | ^ 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 ==== | ==== wiki.getRPCVersionSupported ==== | ||
Line 145: | Line 233: | ||
==== wiki.getPageVersions ==== | ==== wiki.getPageVersions ==== | ||
- | ^ Name | '' | + | ^ Name |
- | ^ Parameters | + | ^ Parameters |
- | ^ Data | (array) each array item holds the following data: \\ \\ < | + | ^ Data |
$data[' | $data[' | ||
$data[' | $data[' | ||
$data[' | $data[' | ||
- | $data[' | + | $data[' |
- | $data[' | + | $data[' |
- | </ | + | ^ Description |
- | ^ Description | Returns the available versions of a Wiki page. The number of pages in the result is controlled via the [[: | + | |
==== wiki.getPageInfo ==== | ==== wiki.getPageInfo ==== | ||
Line 246: | Line 333: | ||
^ Parameters | ^ Parameters | ||
^ Data | (array) each array item holds the following data: \\ \\ < | ^ Data | (array) each array item holds the following data: \\ \\ < | ||
+ | $data[' | ||
$data[' | $data[' | ||
+ | $data[' | ||
$data[' | $data[' | ||
$data[' | $data[' | ||
Line 252: | Line 341: | ||
$data[' | $data[' | ||
</ | </ | ||
- | ^ Description | Returns a list of media files in a given namespace. The options are passed directly to [[xref> | + | ^ Description | Returns a list of media files in a given namespace. The options are passed directly to [[xref> |
==== wiki.getAttachment ==== | ==== wiki.getAttachment ==== | ||
Line 258: | Line 347: | ||
^ Parameters | ^ Parameters | ||
^ Data | (string) the data of the file, encoded in base64 | | ^ Data | (string) the data of the file, encoded in base64 | | ||
- | ^ Description | Returns the binary data of a media file | | + | ^ Description | Returns the binary data of a media file. | |
==== wiki.getAttachmentInfo ==== | ==== wiki.getAttachmentInfo ==== | ||
Line 265: | Line 354: | ||
^ Data | (array) an array containing the following information about the file: \\ \\ < | ^ Data | (array) an array containing the following information about the file: \\ \\ < | ||
$data[' | $data[' | ||
- | ^ Description | Returns information about a media file | | + | ^ Description | Returns information about a media file. | |
==== wiki.putAttachment ==== | ==== wiki.putAttachment ==== | ||
^ Name | '' | ^ Name | '' | ||
- | ^ Parameters | + | ^ Parameters |
+ | existing media object of the given id.</ | ||
^ Data | | | ^ Data | | | ||
- | ^ Description | Uploads a file as a given media id. Available parameters are: \\ \\ < | + | ^ Description | Uploads a file as a given media id. | |
==== wiki.deleteAttachment ==== | ==== wiki.deleteAttachment ==== | ||
Line 278: | Line 368: | ||
^ Data | | | ^ Data | | | ||
^ Description | Deletes a file. Fails if the file is still referenced from any page in the wiki. | | ^ Description | Deletes a file. Fails if the file is still referenced from any page in the wiki. | | ||
+ | |||
+ | ==== plugin.acl.listAcls ==== | ||
+ | ^ Name | '' | ||
+ | ^ Parameters | ||
+ | ^ Data | (array) of ACLs {scope, user, permission}' | ||
+ | ^ Description | Get the list of all ACLs. | | ||
==== plugin.acl.addAcl ==== | ==== plugin.acl.addAcl ==== | ||
Line 283: | Line 379: | ||
^ Parameters | ^ Parameters | ||
^ Data | (boolean) return true if the rule was correctly added| | ^ Data | (boolean) return true if the rule was correctly added| | ||
- | ^ Description | Add an ACL rule. Use '' | + | ^ Description | Add an ACL rule. Use '' |
==== plugin.acl.delAcl ==== | ==== plugin.acl.delAcl ==== | ||
Line 289: | Line 385: | ||
^ Parameters | ^ Parameters | ||
^ Data | (boolean) return true if the rules were correctly deleted| | ^ Data | (boolean) return true if the rules were correctly deleted| | ||
- | ^ Description | Delete any ACL rule matching the given scope and user. Use '' | + | ^ Description | Delete any ACL rule matching the given scope and user. Use '' |
=====Adding methods to the XML-RPC API===== | =====Adding methods to the XML-RPC API===== | ||
Use [[plugintype> | Use [[plugintype> | ||
+ | |||
+ | A summary of recent plugins which indicate Remote support: | ||
+ | |||
+ | ---- pluginquery ----- | ||
+ | SELECT: name, description | ||
+ | WHERE: | ||
+ | VALUES: 63, 128, @DATEMOSTRECENT@, | ||
+ | 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]]. | To implement such a plugin please have a look at the [[remote plugins|remote plugins development documentation]]. | ||
Line 330: | Line 435: | ||
* //320 -> Search result errors// | * //320 -> Search result errors// | ||
* 321 -> No changes in specified timeframe | * 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: | Additionally there are some server error codes that indicate some kind of server or XML-RPC failure. The codes are the following: | ||
Line 338: | Line 447: | ||
* -32603 -> Not authorized to call the requested method (No login or invalid login data was given). | * -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). | * -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. | * -32700 -> Parse Error. Request not well formed. | ||
* -32800 -> Recursive calls to system.multicall are forbidden. | * -32800 -> Recursive calls to system.multicall are forbidden. | ||
* -99999 -> Unknown server error. | * -99999 -> Unknown server error. | ||
- | ===== Sample | + | ===== Sample |
- | A java client for Dokuwiki is available on [[https:// | + | |
- | + | ||
- | Example which displays the title of the wiki and the list of its pages: | + | |
- | <code java> | + | |
- | import dw.xmlrpc.DokuJClient; | + | |
- | import dw.xmlrpc.Page; | + | |
- | + | ||
- | public class Main { | + | |
- | public static void main(String[] args) throws Exception{ | + | |
- | String url = " | + | |
- | String user = " | + | |
- | String pwd = " | + | |
- | + | ||
- | DokuJClient client = new DokuJClient(url, | + | |
- | System.out.println(" | + | |
- | 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 [[http:// | + | |
- | * The URL of the DW-Server must be given **without** the procotol (< | + | |
- | + | ||
- | <code php> | + | |
- | <?php | + | |
- | include(' | + | |
- | + | ||
- | // create a new client instance | + | |
- | $c = new xmlrpc_client('/ | + | |
- | + | ||
- | // enable debugging to see more infos :-) (well, not for production code) | + | |
- | $c-> | + | |
- | + | ||
- | // create the XML message to send | + | |
- | $m = new xmlrpcmsg(' | + | |
- | + | ||
- | // send the message and wait for response | + | |
- | $r = $c-> | + | |
- | if($r == false) die(' | + | |
- | if(!$r-> | + | |
- | // seems good. Now do whatever you want with the data | + | |
- | $v = php_xmlrpc_decode($r-> | + | |
- | echo " | + | |
- | } | + | |
- | </ | + | |
- | + | ||
- | <code php> | + | |
- | <?php | + | |
- | include('/ | + | |
- | + | ||
- | $c = new xmlrpc_client('/ | + | |
- | $c-> | + | |
- | + | ||
- | $m = new xmlrpcmsg(' | + | |
- | $m-> | + | |
- | $m-> | + | |
- | $m-> | + | |
- | + | ||
- | $r = $c-> | + | |
- | if($r == false) die(' | + | |
- | + | ||
- | // Output the response object | + | |
- | // var_dump($r); | + | |
- | $r = $c-> | + | |
- | + | ||
- | if(!$r-> | + | |
- | $v = php_xmlrpc_decode($r-> | + | |
- | echo $v; | + | |
- | } else { | + | |
- | echo $r-> | + | |
- | } | + | |
- | + | ||
- | ?> | + | |
- | </ | + | |
- | + | ||
- | DokuWiki has its own XML-RPC library which could also be used. A simple client using that library looks like this: | + | |
- | + | ||
- | <code php> | + | |
- | <?php | + | |
- | require_once(' | + | |
- | + | ||
- | $client = new IXR_Client(' | + | |
- | $client-> | + | |
- | $client-> | + | |
- | $ok = $client-> | + | |
- | if($ok) { | + | |
- | | + | |
- | echo $client-> | + | |
- | } | + | |
- | </ | + | |
- | + | ||
- | ===== Sample Perl Client ===== | + | |
- | + | ||
- | [[https:// | + | |
- | + | ||
- | you can also write RPC:: | + | |
- | + | ||
- | <code perl> | + | |
- | use strict; | + | |
- | use warnings; | + | |
- | use feature ' | + | |
- | use RPC:: | + | |
- | use Data:: | + | |
- | + | ||
- | my $client = | + | |
- | RPC:: | + | |
- | + | ||
- | my $res = $client-> | + | |
- | say ' | + | |
- | + | ||
- | my $namespace = ' | + | |
- | my $req = | + | |
- | RPC:: | + | |
- | RPC:: | + | |
- | RPC:: | + | |
- | $res = $client-> | + | |
- | say " | + | |
- | + | ||
- | + | ||
- | # if given and >0 ' | + | |
- | # setting ' | + | |
- | $res = $client-> | + | |
- | RPC:: | + | |
- | RPC:: | + | |
- | RPC:: | + | |
- | ) | + | |
- | ); | + | |
- | say " | + | |
- | + | ||
- | + | ||
- | </ | + | |
- | + | ||
- | ===== Sample Ruby Client ===== | + | |
- | This simple example will pull the version information from the given Dokuwiki. No plugin required (in the Windows default package). | + | |
- | <code ruby> | + | |
- | require " | + | |
- | server = XMLRPC:: | + | |
- | begin | + | |
- | puts server.call(" | + | |
- | rescue XMLRPC:: | + | |
- | puts " | + | |
- | puts e.faultCode | + | |
- | puts e.faultString | + | |
- | end | + | |
- | </ | + | |
- | + | ||
- | This example demonstrates how to upload attachments: | + | |
- | + | ||
- | <code ruby> | + | |
- | require " | + | |
- | server = XMLRPC:: | + | |
- | begin | + | |
- | puts server.call(" | + | |
- | rescue XMLRPC:: | + | |
- | puts " | + | |
- | puts e.faultCode | + | |
- | puts e.faultString | + | |
- | end | + | |
- | </ | + | |
- | + | ||
- | ===== Sample jQuery Client ===== | + | |
- | <code javascript> | + | |
- | var xml='<? | + | |
- | | + | |
- | url: " | + | |
- | data: xml, | + | |
- | | + | |
- | | + | |
- | }); | + | |
- | </ | + | |
- | + | ||
- | ===== Python Module ===== | + | |
- | A Python module for DokuWiki' | + | |
- | + | ||
- | ===== Sample AutoIt3 Client ===== | + | |
- | My AutoIt3 client is mainly a proof of concept: | + | |
- | + | ||
- | <code autoit> | + | |
- | #cs ---------------------------------------------------------------------------- | + | |
- | + | ||
- | | + | |
- | | + | |
- | + | ||
- | | + | |
- | XML-RPC sample client AutoIt3 script. | + | |
- | + | ||
- | #ce ---------------------------------------------------------------------------- | + | |
- | + | ||
- | ; this script uses the UDF WinHttp | + | |
- | #include " | + | |
- | + | ||
- | ; get the info from page ' | + | |
- | $Xml = '<? | + | |
- | $Xml = $Xml & @CRLF & '< | + | |
- | $Xml = $Xml & @CRLF & '< | + | |
- | $Xml = $Xml & @CRLF & '< | + | |
- | $Xml = $Xml & @CRLF & '< | + | |
- | $Xml = $Xml & @CRLF & '< | + | |
- | $Xml = $Xml & @CRLF & '< | + | |
- | $Xml = $Xml & @CRLF & '</ | + | |
- | $Xml = $Xml & @CRLF & '</ | + | |
- | $Xml = $Xml & @CRLF & '</ | + | |
- | $Xml = $Xml & @CRLF & '</ | + | |
- | $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, | + | |
- | + | ||
- | ; creates a HTTP request handle | + | |
- | $h_openRequest = _WinHttpOpenRequest($hw_connect, | + | |
- | + | ||
- | ; sends the specified request to the HTTP server | + | |
- | _WinHttpSendRequest($h_openRequest, | + | |
- | + | ||
- | ; 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& | + | |
- | Until @error | + | |
- | + | ||
- | ; close connection and clean up | + | |
- | _WinHttpCloseHandle($h_openRequest) | + | |
- | _WinHttpCloseHandle($hw_connect) | + | |
- | _WinHttpCloseHandle($hw_open) | + | |
- | + | ||
- | ; show error number and resulting data | + | |
- | MsgBox(4096," | + | |
- | </ | + | |
- | + | ||
- | ===== Sample Emacs Lisp Client ===== | + | |
- | <code lisp> | + | |
- | + | ||
- | (require ' | + | |
- | (defvar *dokuwiki-xml-rpc-url* " | + | |
- | (xml-rpc-method-call | + | |
- | ' | + | |
- | + | ||
- | </ | + | |
- | + | ||
+ | A number of [[devel: |
devel/xmlrpc.1427879893.txt.gz · Last modified: 2015-04-01 11:18 by 81.174.162.206