General Actions:
XML-RPC API
Last modified by Jared Scott on 2010/02/12 18:18
Contents
XWiki instances can be accessed remotely using the XML-RPC protocol.
XML-RPC is a remote procedure call protocol which uses XML to encode its calls and HTTP as a transport mechanism
-Wikipedia
XML-RPC makes it easy to build your own 3rd party applications which can connect to your XWiki instances. For example this feature can be helpful to integrate XWiki with other existing Java applications. To be more precise, the XML-RPC feature could be used to provide XWiki functionality to other applications. In such a case, XWiki acts as your content repository accessible directly as well as through your 3rd party applications.
Features
XWiki implements the most important part of the Confluence XML-RPC API.
- Authenticated and anonymous access
- Spaces: retrieval, creation and removal
- Pages: retrieval, rendering, creation, history, update, search and removal
- Attachments: retrieval(download), creation(upload), moving/renaming, removal
- Comments: retrieval, creation and removal
For more information about the Confluence XML-RPC API check out this documentation. In the future we plan to extend this API with XWiki-specific features - any extensions will be documented here.
XML-RPC Clients
There are XML-RPC libraries for most programming languages.
Java Clients
Apache XML-RPC Client
For Java the most well-known one is Apache XML-RPC, which is also used in the implementation of XWiki (i.e. server-side). Here is an example which uses Apache XML-RPC directly in order to get the rendered content of a wiki page (for a much easier way to achieve the same result see the "Client-side Proxy for Java" section below).
import java.net.MalformedURLException;
import java.net.URL;
import java.util.Map;
import org.apache.xmlrpc.XmlRpcException;
import org.apache.xmlrpc.client.XmlRpcClient;
import org.apache.xmlrpc.client.XmlRpcClientConfigImpl;
public class RawXmlRpc
{
public static void main(String[] args)
throws MalformedURLException, XmlRpcException
{
XmlRpcClientConfigImpl config = new XmlRpcClientConfigImpl();
URL url = new URL("http://127.0.0.1:8080/xwiki/xmlrpc");
config.setServerURL(url);
XmlRpcClient client = new XmlRpcClient();
client.setConfig(config);
String token = (String)client.execute("confluence1.login",
new Object[] {"Admin", "admin"});
Map page = (Map)client.execute("confluence1.getPage",
new Object[] {token, "Main", "WebHome"});
String pageId = (String)page.get("id");
String content = (String)page.get("content");
String renderedContent = (String)client.execute(
"confluence1.renderContent",
new Object[] {token, "Main", pageId, content});
System.out.print(renderedContent);
}
}
import java.net.URL;
import java.util.Map;
import org.apache.xmlrpc.XmlRpcException;
import org.apache.xmlrpc.client.XmlRpcClient;
import org.apache.xmlrpc.client.XmlRpcClientConfigImpl;
public class RawXmlRpc
{
public static void main(String[] args)
throws MalformedURLException, XmlRpcException
{
XmlRpcClientConfigImpl config = new XmlRpcClientConfigImpl();
URL url = new URL("http://127.0.0.1:8080/xwiki/xmlrpc");
config.setServerURL(url);
XmlRpcClient client = new XmlRpcClient();
client.setConfig(config);
String token = (String)client.execute("confluence1.login",
new Object[] {"Admin", "admin"});
Map page = (Map)client.execute("confluence1.getPage",
new Object[] {token, "Main", "WebHome"});
String pageId = (String)page.get("id");
String content = (String)page.get("content");
String renderedContent = (String)client.execute(
"confluence1.renderContent",
new Object[] {token, "Main", pageId, content});
System.out.print(renderedContent);
}
}
In order for this to work you need to have commons-logging-1.1.1.jar, ws-commons-util-1.0.1.jar, xmlrpc-common-3.0.jar, and xmlrpc-client-3.0.jar in your classpath (version numbers are irrelevant).
Client-side Proxy for Java
You can build Java applications that use XWiki through the XML-RPC interface easier by using the client-side proxy that is part of XWiki. This proxy is based on Swizzle Confluence and eliminates most of the plumbing needed to use XML-RPC directly. For instance the example above is much simpler when rewritten to use the proxy.
import org.xwiki.xmlrpc.XWikiXmlRpcClient;
import org.xwiki.xmlrpc.model.XWikiPage;
public class ProxyXmlRpc
{
public static void main(String[] args) throws XWikiClientException
{
String url = "http://127.0.0.1:8080/xwiki/xmlrpc/confluence";
String user = "WikiUser";
String pass = "password";
XWikiXmlRpcClient rpc = new XWikiXmlRpcClient(url);
rpc.login(user, pass);
XWikiPage page = rpc.getPage("Main.WebHome");
String rendered = rpc.renderContent(
page.getSpace(), page.getId(), page.getContent());
System.out.print(rendered);
}
}
import org.xwiki.xmlrpc.model.XWikiPage;
public class ProxyXmlRpc
{
public static void main(String[] args) throws XWikiClientException
{
String url = "http://127.0.0.1:8080/xwiki/xmlrpc/confluence";
String user = "WikiUser";
String pass = "password";
XWikiXmlRpcClient rpc = new XWikiXmlRpcClient(url);
rpc.login(user, pass);
XWikiPage page = rpc.getPage("Main.WebHome");
String rendered = rpc.renderContent(
page.getSpace(), page.getId(), page.getContent());
System.out.print(rendered);
}
}
In order for this to work you need to have commons-logging-1.1.1.jar, ws-commons-util-1.0.1.jar, xmlrpc-common-3.0.jar, xmlrpc-client-3.0.jar, xwiki-core-1.5.jar, and swizzle-confluence-1.2-20080419-xwiki.jar, xwiki-core-xmlrpc-client-1.5.jar, xwiki-core-xmlrpc-model-1.5.jar in your classpath (version numbers are for the most part irrelevant).
You can also try this Groovy script in an XWiki Page in your wiki (you need to add xwiki-core-xmlrpc-client-1.5.jar to yours WEB-INF/lib.
<%
import org.xwiki.xmlrpc.XWikiXmlRpcClient;
import org.xwiki.xmlrpc.model.XWikiPage;
String url = "http://localhost:8080/xwiki/xmlrpc/confluence";
String user = "WikiUser";
String pass = "password";
XWikiXmlRpcClient rpc = new XWikiXmlRpcClient(url);
rpc.login(user, pass);
XWikiPage page = rpc.getPage("Main.WebHome");
println(page.getContent());
String rendered = rpc.renderContent(
page.getSpace(), page.getId(), page.getContent());
println(rendered);
%>
import org.xwiki.xmlrpc.XWikiXmlRpcClient;
import org.xwiki.xmlrpc.model.XWikiPage;
String url = "http://localhost:8080/xwiki/xmlrpc/confluence";
String user = "WikiUser";
String pass = "password";
XWikiXmlRpcClient rpc = new XWikiXmlRpcClient(url);
rpc.login(user, pass);
XWikiPage page = rpc.getPage("Main.WebHome");
println(page.getContent());
String rendered = rpc.renderContent(
page.getSpace(), page.getId(), page.getContent());
println(rendered);
%>
Various Examples
Check the various XML-RPC examples in Java for more details.
Groovy Client
Simple Groovy sample:
import groovy.net.xmlrpc.*
def proxy = new XMLRPCServerProxy("http://www.xwiki.org/xwiki/xmlrpc/confluence")
def token = proxy.confluence1.login("username","password")
def pages = proxy.confluence1.getPages(token, "UserGuide")
print pages
def proxy = new XMLRPCServerProxy("http://www.xwiki.org/xwiki/xmlrpc/confluence")
def token = proxy.confluence1.login("username","password")
def pages = proxy.confluence1.getPages(token, "UserGuide")
print pages
Perl Client
Simple Perl sample using XML::RPC:
#!/usr/bin/perl
use XML::RPC;
use strict;
my ($result, $token);
my $xmlrpc = XML::RPC->new('http://www.xwiki.org/xwiki/xmlrpc/confluence');
$token = $xmlrpc->call( 'confluence1.login',
( 'username', 'password' ) );
$result = $xmlrpc->call( 'confluence1.getPages',
( $token, 'UserGuide' ) );
foreach my $elem (@{$result}) {
foreach my $key (keys( %{$elem})) {
printf "%s->%sn", $key, $elem->{$key};
}
}
use XML::RPC;
use strict;
my ($result, $token);
my $xmlrpc = XML::RPC->new('http://www.xwiki.org/xwiki/xmlrpc/confluence');
$token = $xmlrpc->call( 'confluence1.login',
( 'username', 'password' ) );
$result = $xmlrpc->call( 'confluence1.getPages',
( $token, 'UserGuide' ) );
foreach my $elem (@{$result}) {
foreach my $key (keys( %{$elem})) {
printf "%s->%sn", $key, $elem->{$key};
}
}
Python Client
Example of uploading an attachment using python:
import xmlrpclib
proxy = xmlrpclib.ServerProxy("http://localhost:8080/xwiki/xmlrpc/")
token = proxy.confluence1.login("Admin","admin")
page = proxy.confluence1.getPage(token, "Space.TargetPage")
attachment = {'fileName':'TargetFileName.gif','contentType':'image/gif','comment':'ignored','pageId':page.get('id')}
data = xmlrpclib.Binary(open("SomeImage.gif").read())
proxy.confluence1.addAttachment(token, 0, attachment, data)
proxy = xmlrpclib.ServerProxy("http://localhost:8080/xwiki/xmlrpc/")
token = proxy.confluence1.login("Admin","admin")
page = proxy.confluence1.getPage(token, "Space.TargetPage")
attachment = {'fileName':'TargetFileName.gif','contentType':'image/gif','comment':'ignored','pageId':page.get('id')}
data = xmlrpclib.Binary(open("SomeImage.gif").read())
proxy.confluence1.addAttachment(token, 0, attachment, data)
Ruby Client
Example of connecting to the server and retrieving a page using ruby:
require 'xmlrpc/client'
server = XMLRPC::Client.new2("http://localhost:8080/xwiki/xmlrpc/confluence")
token = server.call("confluence1.login", "Admin", "admin")
server.call("confluence1.getPage", token, "Sandbox.WebHome")
server = XMLRPC::Client.new2("http://localhost:8080/xwiki/xmlrpc/confluence")
token = server.call("confluence1.login", "Admin", "admin")
server.call("confluence1.getPage", token, "Sandbox.WebHome")