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:

* [provide an automatic system to send emails when pages change|EmailGenerator]
* [print out all pages of a wiki for inclusion on portable devices|Hula]
* remotely backup a wiki
* transfer pages from one wiki to another, e.g. system and help pages
----

!!!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. [MoinMoin:FlorianFesti]


''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|http://xmlrpc-c.sourceforge.net/xmlrpc-howto/xmlrpc-howto-api-introspection.html].''

* __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

* 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]. 

----

!!Sample Client code

using apache-xmlrpc-3.1.2
%%prettify
{{{
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

* [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]
* [WikiGateway]
* Trac: [http://trac-hacks.org/wiki/XmlRpcPlugin]
* [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 [WikiRPCInterface] for the previous version of the API.
* [HowWikiComparesToRest|http://internet.conveyor.com/RESTwiki/moin.cgi/HowWikiComparesToRest]

----

!!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:

#)  ask the server for a key (ie a string, probably server specific, but something like current date + time + a random string)
#)  encode a password with the key using, eg MD5
#)  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|http://www.cis.ohio-state.edu/cgi-bin/rfc/rfc2095.html]


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|http://phpwiki.sourceforge.net/phpwiki/index.php/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|http://xmlrpc-epi.sourceforge.net/specs/rfc.system.describeMethods.php] 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|http://phpwiki.sourceforge.net/phpwiki/index.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