Mercurial > p > roundup > code

annotate doc/xmlrpc.txt @ 4449:3f251efd5f48

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add "lookup" method to xmlrpc interface (Ralf Schlatterbeck)
author Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
date Fri, 29 Oct 2010 10:41:39 +0000
parents a70dbbc7f967
children 23de24f57566
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
1 =========================
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
2 XML-RPC access to Roundup
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
3 =========================
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
4
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
5 .. contents::
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
6
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
7 Introduction
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
8 ------------
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
9 Version 1.4 of Roundup includes an XML-RPC frontend. Some installations find
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
10 that roundup-admins requirement of local access to the tracker instance
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
11 limiting. The XML-RPC frontend provides the ability to execute a limited subset
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
12 of commands similar to those found in roundup-admin from remote machines.
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
13
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
14 roundup-xmlrpc-server
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
15 ---------------------
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
16 The Roundup XML-RPC server must be started before remote clients can access the
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
17 tracker via XML-RPC. ``roundup-xmlrpc-server`` is installed in the scripts
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
18 directory alongside ``roundup-server`` and roundup-admin``. When invoked, the
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
19 location of the tracker instance must be specified.
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
20
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
21 roundup-xmlrpc-server -i ``/path/to/tracker``
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
22
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
23 The default port is ``8000``. An alternative port can be specified with the
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
24 ``--port`` switch.
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
25
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
26 security consideration
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
27 ======================
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
28 Note that the current ``roundup-xmlrpc-server`` implementation does not
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
29 support SSL. This means that usernames and passwords will be passed in
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
30 cleartext unless the server is being proxied behind another server (such as
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
31 Apache or lighttpd) that provide SSL.
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
32
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
33 client API
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
34 ----------
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
35 The server currently implements four methods. Each method requires that the
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
36 user provide a username and password in the HTTP authorization header in order
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
37 to authenticate the request against the tracker.
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
38
3969
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
39 ======= ====================================================================
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
40 Command Description
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
41 ======= ====================================================================
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
42 list arguments: *classname, [property_name]*
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
43
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
44 List all elements of a given ``classname``. If ``property_name`` is
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
45 specified, that is the property that will be displayed for each
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
46 element. If ``property_name`` is not specified the default label
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
47 property will be used.
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
48
3969
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
49 display arguments: *designator, [property_1, ..., property_N]*
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
50
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
51 Display a single item in the tracker as specified by ``designator``
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
52 (e.g. issue20 or user5). The default is to display all properties
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
53 for the item. Alternatively, a list of properties to display can be
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
54 specified.
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
55
3969
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
56 create arguments: *classname, arg_1 ... arg_N*
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
57
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
58 Create a new instance of ``classname`` with ``arg_1`` through
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
59 ``arg_N`` as the values of the new instance. The arguments are
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
60 name=value pairs (e.g. ``status='3'``).
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
61
3969
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
62 set arguments: *designator, arg_1 ... arg_N*
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
63
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
64 Set the values of an existing item in the tracker as specified by
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
65 ``designator``. The new values are specified in ``arg_1`` through
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
66 ``arg_N``. The arguments are name=value pairs (e.g. ``status='3'``).
4257
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
67
4449
3f251efd5f48 Add "lookup" method to xmlrpc interface (Ralf Schlatterbeck)
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4257
diff changeset
68 lookup arguments: *classname, key_value*
3f251efd5f48 Add "lookup" method to xmlrpc interface (Ralf Schlatterbeck)
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4257
diff changeset
69
3f251efd5f48 Add "lookup" method to xmlrpc interface (Ralf Schlatterbeck)
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4257
diff changeset
70 looks up the key_value for the given class. The class needs to
3f251efd5f48 Add "lookup" method to xmlrpc interface (Ralf Schlatterbeck)
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4257
diff changeset
71 have a key and the user needs search permission on the key
3f251efd5f48 Add "lookup" method to xmlrpc interface (Ralf Schlatterbeck)
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4257
diff changeset
72 attribute and id for the given classname.
3f251efd5f48 Add "lookup" method to xmlrpc interface (Ralf Schlatterbeck)
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4257
diff changeset
73
4257
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
74 filter arguments: *classname, list or None, attributes*
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
75
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
76 list can be None (requires ``allow_none=True`` when
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
77 instantiating the ServerProxy) to indicate search for all values,
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
78 or a list of ids. The attributes are given as a dictionary of
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
79 name value pairs to search for.
3969
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
80 ======= ====================================================================
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
81
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
82 sample python client
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
83 ====================
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
84 ::
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
85
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
86 >>> import xmlrpclib
4257
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
87 >>> roundup_server = xmlrpclib.ServerProxy('http://username:password@localhost:8000', allow_none=True)
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
88 >>> roundup_server.list('user')
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
89 ['admin', 'anonymous', 'demo']
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
90 >>> roundup_server.list('issue', 'id')
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
91 ['1']
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
92 >>> roundup_server.display('issue1')
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
93 {'assignedto' : None, 'files' : [], 'title' = 'yes, ..... }
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
94 >>> roundup_server.display('issue1', 'priority', 'status')
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
95 {'priority' : '1', 'status' : '2'}
3951
53b922e0d2b7 typo in docs for xmlrpc
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3950
diff changeset
96 >>> roundup_server.set('issue1', 'status=3')
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
97 >>> roundup_server.display('issue1', 'status')
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
98 {'status' : '3' }
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
99 >>> roundup_server.create('issue', "title='another bug'", "status=2")
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
100 '2'
4257
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
101 >>> roundup_server.filter('user',None,{'username':'adm'})
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
102 ['1']
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
103 >>> roundup_server.filter('user',['1','2'],{'username':'adm'})
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
104 ['1']
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
105 >>> roundup_server.filter('user',['2'],{'username':'adm'})
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
106 []
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
107 >>> roundup_server.filter('user',[],{'username':'adm'})
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
108 []
4449
3f251efd5f48 Add "lookup" method to xmlrpc interface (Ralf Schlatterbeck)
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4257
diff changeset
109 >>> roundup_server.lookup('user','admin')
3f251efd5f48 Add "lookup" method to xmlrpc interface (Ralf Schlatterbeck)
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4257
diff changeset
110 '1'
Roundup Issue Tracker: http://roundup-tracker.org/