This is an XML-RPC interface for Wikis, so that you can do all sorts of interesting scripting and stuff. For example, it has been used to do things like:
- provide an automatic system to send emails when pages change
- print out all pages of a wiki for inclusion on portable devices
- Enable a wiki page to control the configuration of a complicated Python process. This supersedes a process wherein the person desiring changes had to ask an engineer to check out the code and add the info.
API#
Version 1 API is as follows:
- array getRecentChanges( Date timestamp ): Get list of changed pages since timestamp, which should be in UTC. The result is an array, where each element is a struct:
- name (string) : Name of the page. The name is UTF-8 with URL encoding to make it ASCII.
- lastModified (date) : Date of last modification, in UTC.
- author (string) : Name of the author (if available). Again, name is UTF-8 with URL encoding.
- version (int) : Current version.
- A page MAY be specified multiple times. A page MAY NOT be specified multiple times with the same modification date.
- int getRPCVersionSupported(): Returns 1 with this version of the JSPWiki API.
- base64 getPage( String pagename ): Get the raw Wiki text of page, latest version. Page name must be UTF-8, with URL encoding. Returned value is a binary object, with UTF-8 encoded page data.
- base64 getPageVersion( String pagename, int version ): Get the raw Wiki text of page. Returns UTF-8, expects UTF-8 with URL encoding.
- base64 getPageHTML( String pagename ): Return page in rendered HTML. Returns UTF-8, expects UTF-8 with URL encoding.
- base64 getPageHTMLVersion( String pagename, int version ): Return page in rendered HTML, UTF-8.
- array getAllPages(): Returns a list of all pages. The result is an array of strings, again UTF-8 in URL encoding.
- struct getPageInfo( string pagename ) : returns a struct with elements
- name (string): the canonical page name, URL-encoded UTF-8.
- lastModified (date): Last modification date, UTC.
- author (string): author name, URL-encoded UTF-8.
- version (int): current version
- struct getPageInfoVersion( string pagename, int version ) : returns a struct just like plain getPageInfo(), but this time for a specific version.
- array listLinks( string pagename ): Lists all links for a given page.
The returned array contains structs, with the following elements:
- page (string) : The page name or URL the link is to.
- type (string) : The link type. This is a string, with the following
possible values:
- "external" : The link is an external hyperlink
- "local" : This is a local Wiki name for hyperlinking
- href (string) : The HREF the link points to. Useful for finding this link within the HTML of this page.
As you can see, all data is returned in a base64 -type in UTF-8 encoding, regardless of what JSPWiki preference actually is. Also, all incoming or outcoming strings are really UTF-8, but they have been URL-encoded so that the XML-RPC requirement of ASCII is fulfilled.
The URL is http://www.jspwiki.org/RPC2/ (note the trailing slash). All methods are prepended with wiki. - for example, wiki.getAllPages()
Errors#
All methods which handle a page in any way can return a Fault. Current fault codes are:
- 1 : No such page was found.
Troubleshooting#
You should make sure that XMLRPC is enabled in the deployment descriptor (WEB-INF/web.xml)See comments there.
JSPWiki specific notes#
We also offer a non-spec compliant service at URL:
The XML-RPC service here is otherwise exactly the same as the one detailed above, except that all strings are considered to be UTF-8, and all methods that use base64, use strings. So, if you don't want to do any Base64-conversions for strings, just use the UTF-8 API.
Related Code#
- A client Java API for this interface can be found at Hula, as well as some sample apps.
- A project to present this interface on top of existing Wiki's is noted at Hoop.
- Also, see EmailGenerator, http://www.mahlen.org/jspwiki/
, and TouchGraphWikiBrowser.
Other implementations#
- OpenWiki: http://www.protocol7.com/services/openwiki.asp
- TWiki: http://www.decafbad.com/twiki/bin/view/Main/XmlRpcToWiki
- UseModWiki: http://www.decafbad.com/twiki/bin/view/Main/XmlRpcToWiki
- MoinMoin: http://www.decafbad.com/twiki/bin/view/Main/XmlRpcToWiki
- PhpWiki: http://phpwiki.sourceforge.net/phpwiki-1.2/index.php?XmlRpc
Related Discussions#
- See WikiRPCInterfaceUTF8VsBase64 for more on UTF-8 issues and time zone stuff.
- See WikiRPCInterfaceListLinks for the discussion on the listLinks() method.
- See WikiRPCInterfaceDiscussion for generic discussion about this interface.
- See WikiRPCInterface2 for discussion on the next version of the API.
- HowWikiComparesToRest
please try to coordinate this effort with other wikis, for example have a look at http://meta.wikimedia.org/w/wiki.phtml?title=Machine-friendly_wiki_interface and talk to the people there.
Well, AFAIK this is the oldest API there is, so others should be co-ordinating with us ;-). Anyway, this API is pretty much obsolete. It's far better to use something like AtomPublishingProtocol.