Mercurial > p > roundup > code

annotate doc/xmlrpc.txt @ 4531:ddff9669361b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Fix matching of incoming email addresses to the alternate_addresses field... ...of a user -- this would match substrings, e.g. if the user has discuss-support@example.com as an alternate email and an incoming mail is addressed to support@example.com this would (wrongly) match. Note: I *think* I've seen this discussed somewhere but couldn't find it, neither in the tracker nor in recent discussions on the mailinglists. So if someone remembers an issue which now should be closed, please tell me :-)
author Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
date Wed, 24 Aug 2011 14:43:52 +0000
parents 3f251efd5f48
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/