Mercurial > p > roundup > code

annotate doc/xmlrpc.txt @ 4929:57a482110a24

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: Link XMLRPC `filter` doc to User Guide chapter about querying
author anatoly techtonik <techtonik@gmail.com>
date Mon, 29 Sep 2014 18:37:26 +0300
parents 08a5a47855cb
children f47c35727b3e
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::
4890
609edf9de0a5 docs: Remove one nesting level from ToC on subpages
anatoly techtonik <techtonik@gmail.com>
parents: 4732
diff changeset
6 :local:
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
7
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
8 Introduction
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
9 ------------
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
10 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
11 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
12 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
13 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
14
4678
23de24f57566 issue2550749 - the xmlrpc interface is invoked on content type
rouilj
parents: 4449
diff changeset
15 There are two ways to access the xmlrpc interface:
23de24f57566 issue2550749 - the xmlrpc interface is invoked on content type
rouilj
parents: 4449
diff changeset
16
23de24f57566 issue2550749 - the xmlrpc interface is invoked on content type
rouilj
parents: 4449
diff changeset
17 stand alone roundup-xmlrpc-server
23de24f57566 issue2550749 - the xmlrpc interface is invoked on content type
rouilj
parents: 4449
diff changeset
18
23de24f57566 issue2550749 - the xmlrpc interface is invoked on content type
rouilj
parents: 4449
diff changeset
19 access via the roundup server
23de24f57566 issue2550749 - the xmlrpc interface is invoked on content type
rouilj
parents: 4449
diff changeset
20
23de24f57566 issue2550749 - the xmlrpc interface is invoked on content type
rouilj
parents: 4449
diff changeset
21
23de24f57566 issue2550749 - the xmlrpc interface is invoked on content type
rouilj
parents: 4449
diff changeset
22 stand alone roundup-xmlrpc-server
4732
8ee41c7372e7 doc: Fix some Sphinx warnings.
anatoly techtonik <techtonik@gmail.com>
parents: 4678
diff changeset
23 ---------------------------------
4678
23de24f57566 issue2550749 - the xmlrpc interface is invoked on content type
rouilj
parents: 4449
diff changeset
24 The Roundup XML-RPC standalone server must be started before remote clients can access the
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
25 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
26 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
27 location of the tracker instance must be specified.
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
28
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
29 roundup-xmlrpc-server -i ``/path/to/tracker``
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
30
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
31 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
32 ``--port`` switch.
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
33
4678
23de24f57566 issue2550749 - the xmlrpc interface is invoked on content type
rouilj
parents: 4449
diff changeset
34 accessing via roundup server
23de24f57566 issue2550749 - the xmlrpc interface is invoked on content type
rouilj
parents: 4449
diff changeset
35 ----------------------------
23de24f57566 issue2550749 - the xmlrpc interface is invoked on content type
rouilj
parents: 4449
diff changeset
36 In addition to running a stand alone server described above, the
23de24f57566 issue2550749 - the xmlrpc interface is invoked on content type
rouilj
parents: 4449
diff changeset
37 xmlrpc service is available from the roundup HTTP server. Access it by
23de24f57566 issue2550749 - the xmlrpc interface is invoked on content type
rouilj
parents: 4449
diff changeset
38 sending text/xml data to the URL for the roundup tracker with the last
23de24f57566 issue2550749 - the xmlrpc interface is invoked on content type
rouilj
parents: 4449
diff changeset
39 component of the url set to 'xmlrpc'.
23de24f57566 issue2550749 - the xmlrpc interface is invoked on content type
rouilj
parents: 4449
diff changeset
40
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
41 security consideration
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
42 ======================
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
43 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
44 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
45 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
46 Apache or lighttpd) that provide SSL.
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
47
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
48 client API
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
49 ----------
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
50 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
51 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
52 to authenticate the request against the tracker.
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
53
3969
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
54 ======= ====================================================================
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
55 Command Description
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
56 ======= ====================================================================
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
57 list arguments: *classname, [property_name]*
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
58
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
59 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
60 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
61 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
62 property will be used.
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
63
3969
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
64 display arguments: *designator, [property_1, ..., property_N]*
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
65
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
66 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
67 (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
68 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
69 specified.
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
70
3969
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
71 create arguments: *classname, arg_1 ... arg_N*
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
72
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
73 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
74 ``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
75 name=value pairs (e.g. ``status='3'``).
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
76
3969
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
77 set arguments: *designator, arg_1 ... arg_N*
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
78
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
79 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
80 ``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
81 ``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
82
4449
3f251efd5f48 Add "lookup" method to xmlrpc interface (Ralf Schlatterbeck)
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4257
diff changeset
83 lookup arguments: *classname, key_value*
3f251efd5f48 Add "lookup" method to xmlrpc interface (Ralf Schlatterbeck)
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4257
diff changeset
84
3f251efd5f48 Add "lookup" method to xmlrpc interface (Ralf Schlatterbeck)
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4257
diff changeset
85 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
86 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
87 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
88
4257
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
89 filter arguments: *classname, list or None, attributes*
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
90
4929
57a482110a24 doc: Link XMLRPC `filter` doc to User Guide chapter about querying
anatoly techtonik <techtonik@gmail.com>
parents: 4916
diff changeset
91 ``list`` is a list of ids to filter. It can be set to None to run
57a482110a24 doc: Link XMLRPC `filter` doc to User Guide chapter about querying
anatoly techtonik <techtonik@gmail.com>
parents: 4916
diff changeset
92 filter over all values (requires ``allow_none=True`` when
57a482110a24 doc: Link XMLRPC `filter` doc to User Guide chapter about querying
anatoly techtonik <techtonik@gmail.com>
parents: 4916
diff changeset
93 instantiating the ServerProxy). The ``attributes`` are given as a
57a482110a24 doc: Link XMLRPC `filter` doc to User Guide chapter about querying
anatoly techtonik <techtonik@gmail.com>
parents: 4916
diff changeset
94 dictionary of name value pairs to search for. See also :ref:`query-tracker`.
3969
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
95 ======= ====================================================================
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
96
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
97 sample python client
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
98 ====================
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
99 ::
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
100
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
101 >>> import xmlrpclib
4916
08a5a47855cb Fix XMLRPC endpoint in documentation example (changed in 1.4.21)
anatoly techtonik <techtonik@gmail.com>
parents: 4890
diff changeset
102 >>> roundup_server = xmlrpclib.ServerProxy('http://username:password@localhost:8000/xmlrpc', allow_none=True)
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
103 >>> roundup_server.list('user')
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
104 ['admin', 'anonymous', 'demo']
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
105 >>> roundup_server.list('issue', 'id')
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
106 ['1']
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
107 >>> roundup_server.display('issue1')
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
108 {'assignedto' : None, 'files' : [], 'title' = 'yes, ..... }
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
109 >>> roundup_server.display('issue1', 'priority', 'status')
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
110 {'priority' : '1', 'status' : '2'}
3951
53b922e0d2b7 typo in docs for xmlrpc
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3950
diff changeset
111 >>> roundup_server.set('issue1', 'status=3')
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
112 >>> roundup_server.display('issue1', 'status')
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
113 {'status' : '3' }
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
114 >>> 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
115 '2'
4257
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
116 >>> roundup_server.filter('user',None,{'username':'adm'})
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
117 ['1']
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
118 >>> 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
119 ['1']
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
120 >>> roundup_server.filter('user',['2'],{'username':'adm'})
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
121 []
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
122 >>> roundup_server.filter('user',[],{'username':'adm'})
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
123 []
4449
3f251efd5f48 Add "lookup" method to xmlrpc interface (Ralf Schlatterbeck)
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4257
diff changeset
124 >>> roundup_server.lookup('user','admin')
3f251efd5f48 Add "lookup" method to xmlrpc interface (Ralf Schlatterbeck)
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4257
diff changeset
125 '1'
4678
23de24f57566 issue2550749 - the xmlrpc interface is invoked on content type
rouilj
parents: 4449
diff changeset
126
23de24f57566 issue2550749 - the xmlrpc interface is invoked on content type
rouilj
parents: 4449
diff changeset
127 If you are accessing the interface via the roundup HTTP server, a url
23de24f57566 issue2550749 - the xmlrpc interface is invoked on content type
rouilj
parents: 4449
diff changeset
128 similar to:
23de24f57566 issue2550749 - the xmlrpc interface is invoked on content type
rouilj
parents: 4449
diff changeset
129
23de24f57566 issue2550749 - the xmlrpc interface is invoked on content type
rouilj
parents: 4449
diff changeset
130 http://username:password@localhost:8000/tracker/xmlrpc
23de24f57566 issue2550749 - the xmlrpc interface is invoked on content type
rouilj
parents: 4449
diff changeset
131
23de24f57566 issue2550749 - the xmlrpc interface is invoked on content type
rouilj
parents: 4449
diff changeset
132 should be used.
Roundup Issue Tracker: http://roundup-tracker.org/