--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/xmlrpc.txt	Fri Nov 23 20:57:50 2007 +0000
@@ -0,0 +1,88 @@
+=========================
+XML-RPC access to Roundup
+=========================
+
+.. contents::
+
+Introduction
+------------
+Version 1.4 of Roundup includes an XML-RPC frontend. Some installations find
+that roundup-admins requirement of local access to the tracker instance
+limiting. The XML-RPC frontend provides the ability to execute a limited subset
+of commands similar to those found in roundup-admin from remote machines. 
+
+roundup-xmlrpc-server
+---------------------
+The Roundup XML-RPC server must be started before remote clients can access the
+tracker via XML-RPC. ``roundup-xmlrpc-server`` is installed in the scripts
+directory alongside ``roundup-server`` and roundup-admin``. When invoked, the
+location of the tracker instance must be specified.
+
+	roundup-xmlrpc-server -i ``/path/to/tracker``
+
+The default port is ``8000``. An alternative port can be specified with the
+``--port`` switch.
+
+security consideration
+======================
+Note that the current ``roundup-xmlrpc-server`` implementation does not
+support SSL. This means that usernames and passwords will be passed in
+cleartext unless the server is being proxied behind another server (such as
+Apache or lighttpd) that provide SSL.
+
+client API
+----------
+The server currently implements four methods. Each method requires that the
+user provide a username and password in the HTTP authorization header in order
+to authenticate the request against the tracker.
+
+list
+        :arguments: classname, [property_name]
+
+        List all elements of a given ``classname``. If ``property_name`` is
+        specified, that is the property that will be displayed for each
+        element. If ``property_name`` is not specified the default label
+        property will be used.
+
+display
+        :arguments: designator, [property_1, ..., property_N]
+
+        Display a single item in the tracker as specified by ``designator``
+        (e.g. issue20 or user5). The default is to display all properties
+        for the item. Alternatively, a list of properties to display can be
+        specified.
+
+create
+        :arguments: classname, arg_1 ... arg_N
+
+        Create a new instance of ``classname`` with ``arg_1`` through
+        ``arg_N`` as the values of the new instance. The arguments are
+        name=value pairs (e.g. ``status='3'``).
+
+set
+        :arguments: designator, arg_1 ... arg_N
+
+        Set the values of an existing item in the tracker as specified by
+        ``designator``. The new values are specified in ``arg_1`` through
+        ``arg_N``. The arguments are name=value pairs (e.g. ``status='3'``).
+
+sample python client
+====================
+::
+
+        >>> import xmlrpclib
+        >>> roundup_server = xmlrpclib.ServerProxy('http://username:password@localhost:8000')
+        >>> roundup_server.list('user')
+        ['admin', 'anonymous', 'demo']
+        >>> roundup_server.list('issue', 'id')
+        ['1']
+        >>> roundup_server.display('issue1')
+        {'assignedto' : None, 'files' : [], 'title' = 'yes, ..... }
+        >>> roundup_server.display('issue1', 'priority', 'status')
+        {'priority' : '1', 'status' : '2'}
+        >>> roundup_server.set('issue1', 'status=3'
+        >>> roundup_server.display('issue1', 'status')
+        {'status' : '3' }
+        >>> roundup_server.create('issue', "title='another bug'", "status=2")
+        '2'
+