This is Version 2 of 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:


API (Version 2)#

Shortcuts#

  • "utf8": if you see "utf8" as a data type, this has to be read as "the data type String using UTF-8 encoding". If not otherwise stated, that's all - no other encoding like URL-encoding or base64 encapsulating that.
  • All methods are prepended with "wiki." - for example: wiki.getAllPages()

Functions similar to API v1#

As you see below, most data is exchanged in utf8, regardless of what the Wiki's internal preference actually is. Additional encapsulation/encoding is only used if really necessary, like base64 for binary file content.

Notice that this is possible now, because the requirement of xmlrpc Strings being ASCII-only was dropped.

  • 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 (utf8) : Name of the page.
    • lastModified (date) : Date of last modification, in UTC.
    • author (utf8) : Name of the author (if available).
    • 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 2 with this version of the JSPWiki API.
  • utf8 getPage( utf8 pagename ): Get the raw Wiki text of page, latest version.
  • utf8 getPageVersion( utf8 pagename, int version ): Get the raw Wiki text of page.
  • utf8 getPageHTML( utf8 pagename ): Return page in rendered HTML, latest version.
  • utf8 getPageHTMLVersion( utf8 pagename, int version ): Return page in rendered HTML.
  • array getAllPages(): Returns a list of all pages. The result is an array of utf8 pagenames.
  • struct getPageInfo( utf8 pagename ) : returns a struct with elements
    • name (utf8): the canonical page name.
    • lastModified (date): Last modification date, UTC.
    • author (utf8): author name.
    • version (int): current version
  • struct getPageInfoVersion( utf8 pagename, int version ) : returns a struct just like plain getPageInfo(), but this time for a specific version.
  • array listLinks( utf8 pagename ): Lists all links for a given page. The returned array contains structs, with the following elements:
    • page (utf8) : The page name or URL the link is to.
    • type (utf8) : 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 (utf8) : The HREF the link points to. Useful for finding this link within the HTML of this page.

New functions in API v2#

These are the most requested features for API v2:

  • array getBackLinks( utf8 page ) - returns the pages that link to this page.
  • putPage( utf8 page, utf8 content, struct attributes ) - writes the content of the page.
    • The attributes-struct can be used to set any Wiki-specific things, which the server can freely ignore or incorporate. Standard names are:
      • comment (utf8): A comment for a page.
      • minoredit (Boolean???): This was a minor edit only.
      • There is a timestamp or version of the former version missing! If I get a page edit it and write it back all edits during this time get lost (lost update). To fix this the caller must say what version he retrieved, so the wiki can block on conflicts. Aucune référence InterWiki définie dans les propriétés pour le Wiki appelé "MoinMoin" !

Stuff that we probably need

  • array listAttachments( utf8 page ) - Lists attachments on a given page. The array consists of utf8 attachment names that can be fed to getAttachment (or putAttachment).
  • base64 getAttachment( utf8 attachmentName ) - returns the content of an attachment.
  • putAttachment( utf8 attachmentName, base64 content ) - (over)writes an attachment.
  • struct getAttachmentInfo( utf8 attachmentName ) - returns a struct of:
    • lastModified (date) : Last modification date. Not existing file returns 0.
    • size (int) : filesize in bytes of an attachment. Not existing file returns 0.

Introspection

These are the suggested introspection methods from the XML-RPC Howto.

  • array system.listMethods()
  • string system.methodHelp (string methodName)
  • array system.methodSignature (string methodName)

Errors#

All methods which handle a page in any way can return a Fault.

Current fault codes are:

  • 1 : No such page was found.

JSPWiki specific notes#

The URL is http://www.jspwiki.org/RPC2/ (note the trailing slash).

Troubleshooting#

You should make sure that XMLRPC is enabled in the deployment descriptor (WEB-INF/web.xml)
See comments there.

Old stuff - some might refer to v1 and has to be refactored#

Related Code#


Sample Client code#

using apache-xmlrpc-3.1.2

XmlRpcClientConfigImpl config = new XmlRpcClientConfigImpl();
config.setServerURL(new URL("http://localhost:6969/JSPWiki/RPC2/"));
XmlRpcClient client = new XmlRpcClient();
client.setConfig(config);
Object[] params = {};
Object[] result = (Object[]) client.execute("wiki.getAllPages", new Vector(0));
for (int i = 0;i<result.length;i++)
{
	System.out.println(result[i]);
}

Other implementations#


Related Discussions#


Discussion#

Problems of V1#

  • No introspection, i.e. no means to say what exactly is supported, besides getting the pure interface version
    • imagine other interfaces, or local extensions
    • indicating partial implementations
  • Too much assumptions about the underlying wiki, especially that pages are versioned by an integer
    • version has to be a string to be fully portable, and there has to be a getVersionsOfPage() call
    • an empty version means the current page, i.e. we don't need a versioned and unversioned version of each call (pun intended)
  • MahlenMorris: Link to a page that doesn't exist is not differentiated from other internal links.

Options & Introspection#

Introspection is probably a good thing, and should be added, but considering that there is a sort of a fledgling standard already, I am not sure that it should be mandated in the Wiki API.

--JanneJalkanen 11-May-2002

Overloading methods#

Don't need a separate versioned/unversioned methods - I wouldn't trust that XML-RPC client libraries support overloading of methods. A second thing is that we don't want to break the current API unless absolutely necessary.

--JanneJalkanen 11-May-2002

Authentication#

setPageText() requires some sort of user authentication to take place. It has been suggested that we use HTTP Basic authentication, but it might not work with all client libraries. Also, I had a very good reason which I can't remember just now, but I'll write it when I remember it =).

MahlenMorris: Wouldn't this have to work hand-in-glove with the "Authentication and access control" mentioned in JSPWikiV2Features? I would imagine that that level of ACL would be tough to maintain with HTTP authentication (though I'll confess to not knowing the details of HTTP authentication at all).

Also, given your own hesitation to implement setPageText(), it'd be nice if JSPWiki maintainers could easily choose to turn it off. Allowing pages to be set from the outside just seems to alter the whole relationship between a Wiki and the WikiRPCInterface2.

What about a two-stage process:

  1. ) ask the server for a key (ie a string, probably server specific, but something like current date + time + a random string)
  2. ) encode a password with the key using, eg MD5
  3. ) send the username along with the encoded key to the server along with the setPageText request.

eg:

string wiki.getEncodingKey()

string wiki.setPageText(Username: string, EncodedPassword: base64, NewText: base64)

This avoids the need for plaintext passwords to be sent over the network. It is similar to the CRAM-MD5 authentication method for APOP described in RFC 2095

Of course, if the server does not wish to implement authentication for posts, it can either ignore the encoded password sent by the client, or indicate in some way, in reply to the getEncodingKey call, that no password is needed. I would prefer this approach to allowing the server admin to "turn off" the method.

--LawrenceAkka

Versioning#

Could someone display me one version of a Wiki where a version cannot be mapped to an integer? Or even explain when it could be a problem? Or how to make version comparisons if the version is a string?

--JanneJalkanen 11-May-2002

Getting MetaData#

Along those same lines, it'd be nice to have a programmatic way for the XML-RPC client to know if it can usefully call setPageText() or not, which brings me to a further method suggestion:

  • struct getWikiInfo() - Returns a struct of name-value pairs about this Wiki. Possible names and their meanings could include:
    • purpose (utf8) - Human-written description of site.
    • languages (utf8) - comma-separated list of content languages, like "en,de,fr"
    • adminName (utf8) - Name of person who administrates the site.
    • adminEmail (utf8) - Email of person who administrates the site.
    • pageCount (int) - Size of Wiki in pages.
    • mainURL - (utf8) The URL that acts as the front page to this Wiki.
...

This could become the genesis of a UDDI/telephone book for Wiki's. Send some central site your XML-RPC URL, and it can query the Wiki and create pages listing various Wiki's. Heck, people could get a daily delta email across their many chosen Wiki's.

(And let it be pointed out that writing this up now is how I've just spent the night of my 38th birthday. Draw what conclusions you wish.)

Whee, congrats :-). Some XML-RPC servers support a "system.getMethods()" -style approach, which lists all callable methods. Something similar could be supported here as well. Otherwise I think that getWikiInfo is probably a good method to implement. --JanneJalkanen

Take a look here for a proposed standard method: system.describeMethods

You may also be interested in the Java introspection hacks at http://xmlrpc-c.sourceforge.net/hacks.php

--LawrenceAkka

I'd like to be able to ask the server what time it thinks it is. -- LionKimbro

Why? The times are always returned in UTC. --JanneJalkanen


I don't actually know whether this is current in any way anymore. I think we should adopt the Atom API for future work.

-- JanneJalkanen, 06-Feb-2004


I have no idea how to get version 2 of the xmlrpc-Interface. It seems to be no reference in this wiki to download it. Is it reality, under development or only an idea?

-- JoergDudek, 14-May-2004

Just an idea.

-- JanneJalkanen, 16-May-2004

can we add String getEncodingType(pagename) that returns what the wikiMarkup used in that page is? I want to have one client that can get and show topics from all over the place (I'm a twiki guy). the simplest idea that springs to mind is that we can return something of the MimeTypes thing. ie: "text/jspwiki", "text/twiki", "text/c2wiki", "text/moinwiki", "text/aspwiki", "text/usemodwiki" etc.

I'm playing with a few of these ideas in MS's OwikiPad QtPython editor

another need that I have is to allow user specifyable queries (the synatx of wich will initially need to be wiki implementation specific). i was thinking that it could be possible to have an xmlrpc method that renders the submitted text without saving.

eg

  • utf8 render( utf8 content ) : return rendered content as wiki markup
  • utf8 renderAsHtml( utf8 content ) : return rendered content as html

-- SvenDowideit, 10-June-2004

Problems of v2#

I recently changed the version numbers used by moinmoin from UNIX timestamps to UNIX timestamps scaled up by 10e6 (thus, microseconds since 1970 UTC). I did it because the seconds granularity wasn't enough and I didn't want to use floats. After doing all the work, I discovered that xmlrpc ints are limited to 32bits, so my new version numbers don't work. 8(

I propose using a str instead of an int at every place where "version" is used, either/or:

  • Just an identifier of the page, no matter how it looks like. This would also solve version numbers like 1.1.2.3. Problem: order/sorting.
  • Just an integer in string representation. Order is no problem.

-- ThomasWaldmann, 2004-10-24


Problems in 2.4.100...!?#

Hey Folks,

works the XML-RPC-Interface in the new 2.4.100 Version of JSPWiki properly?

I tried this code:

<%@ page import="org.mahlen.hula.rpcclient.LinkInfo"%>
<%@ page import="org.mahlen.hula.rpcclient.RPCClient"%>
<%@ page import="org.apache.log4j.*" %>
<%@ page import="com.ecyrd.jspwiki.*" %>
<%@ page import="java.util.*" %>
<%@ page import="com.ecyrd.jspwiki.tags.WikiTagBase" %>
<%@ page errorPage="/Error.jsp" %>
<%@ taglib uri="/WEB-INF/jspwiki.tld" prefix="wiki" %>

<%!
    public void jspInit()
    {
        wiki = WikiEngine.getInstance( getServletConfig() );
    }

    WikiEngine wiki;
%>

<%

    String wikiName = wiki.safeGetParameter( request,"wiki");
    RPCClient client = new RPCClient("http://myurl.de:15984/"+wikiName+"/RPC2/");

    String[] allPages = client.getAllPages();  // <- Line of Failure

In my Old JSPWiki-Installation it works.. but in the new Version appears an JAVA-Error :

JSPWiki has detected an error
Error Message 
Exception 
java.io.IOException 
Place where detected 
org.apache.xmlrpc.XmlRpcClient$Worker.execute(), line -1 
If you have changed the templates, please do check them. This error message may show up because of that. If you have not changed them, and you are either installing JSPWiki for the first time or have changed configuration, then you might want to check your configuration files. If you are absolutely sure that JSPWiki was running quite okay or you can't figure out what is going on, then by all means, come over to jspwiki.org and tell us. There is more information in the log file (like the full stack trace, which you should add to any error report). 

And don't worry - it's just a computer program. Nothing really serious is probably going on: at worst you can lose a few nights sleep. It's not like it's the end of the world. 

Any Ideas?

Please AnswerMe!

Thanks!

I need ans answer... please!

--MartinU, 17-Apr-2007

Hmm... no Ideas in order of my problem?!

--MartinU, 19-Apr-2007

I really need an answer!! Please!!!!

Martin, I hope you can understand that those of us involved in this project are not getting paid and we (so far as I know) lead very busy professional and personal lives. The question you asked isn't a simple one to answer straightaway and whomever decides to tackle it will have to do some coding and testing. The update of the XML-RPC code in the CVS 2.5.x codebase is different than 2.4.x so that also complicates the picture. If you're willing to pay to get fast service that might be a different matter, but apart from that I hope you have some patience. -- MurrayAltheim, 27-Apr-2007


Just a couple of quick comments:

  • This is so completely the wrong page to ask for something like this (I recommend the JSPWikiMailingList), so that it's no wonder it goes unnoticed :)
  • The error looks like it's coming within Apache XMLRPC lib. So JSPWiki is not likely at fault. Take a look at your classpath (and also let us know what the OLD version of your software is). My guess is that you've made a mistake in web.xml mappings or something. Looks like a config issue anyway. As far as I know, the XML-RPC interface works well with jspwiki 2.4.102.

--JanneJalkanen, 27-Apr-2007

Add new attachment

Only authorized users are allowed to upload new attachments.
« This page (revision-68) was last changed on 27-Mar-2010 08:19 by 169.232.246.94