Mercurial > p > roundup > code

annotate doc/xmlrpc.txt @ 7504:1a912887d704

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Clarify meaning of 'tracker directory' in upgrading doc. now shown as 'tracker home directory' and link to 'tracker home' in glossary added. Also expand on how to identify the tracker home in the glossary term. Prompted by question on irc at: 2023-06-21 09:38:37
author John Rouillard <rouilj@ieee.org>
date Wed, 21 Jun 2023 14:43:31 -0400
parents 924b07252412
children 273c8c2b5042
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6586
24e2eeb2ed9a Add meta description to some doc pages.
John Rouillard <rouilj@ieee.org>
parents: 6370
diff changeset
1 .. meta::
6774
e7b4ad2c57ac landmarks, skiplink, remove bad attrs, autocomplete search
John Rouillard <rouilj@ieee.org>
parents: 6586
diff changeset
2 :description:
6586
24e2eeb2ed9a Add meta description to some doc pages.
John Rouillard <rouilj@ieee.org>
parents: 6370
diff changeset
3 Documentation on the XMLRPC interface to the Roundup Issue
24e2eeb2ed9a Add meta description to some doc pages.
John Rouillard <rouilj@ieee.org>
parents: 6370
diff changeset
4 Tracker. Includes sample clients.
24e2eeb2ed9a Add meta description to some doc pages.
John Rouillard <rouilj@ieee.org>
parents: 6370
diff changeset
5
6167
81ae33038ec5 more index entries.
John Rouillard <rouilj@ieee.org>
parents: 6026
diff changeset
6 .. index:: triple: api; xml; remote procedure call
81ae33038ec5 more index entries.
John Rouillard <rouilj@ieee.org>
parents: 6026
diff changeset
7 pair: api; xmlrpc
81ae33038ec5 more index entries.
John Rouillard <rouilj@ieee.org>
parents: 6026
diff changeset
8
3950
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 XML-RPC access to Roundup
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
11 =========================
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
12
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
13 .. contents::
4890
609edf9de0a5 docs: Remove one nesting level from ToC on subpages
anatoly techtonik <techtonik@gmail.com>
parents: 4732
diff changeset
14 :local:
3950
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 Introduction
7472
db58a86aa29d Redo headers. Elevete lack of ssl to caution.
John Rouillard <rouilj@ieee.org>
parents: 6774
diff changeset
17 ============
db58a86aa29d Redo headers. Elevete lack of ssl to caution.
John Rouillard <rouilj@ieee.org>
parents: 6774
diff changeset
18
4936
eeb9572b0508 doc: Update XML-RPC documentation with example that points to demo
anatoly techtonik <techtonik@gmail.com>
parents: 4930
diff changeset
19 Version 1.4 of Roundup includes an XML-RPC frontend for remote access. The
eeb9572b0508 doc: Update XML-RPC documentation with example that points to demo
anatoly techtonik <techtonik@gmail.com>
parents: 4930
diff changeset
20 XML-RPC interface allows a limited subset of commands similar to those found in
eeb9572b0508 doc: Update XML-RPC documentation with example that points to demo
anatoly techtonik <techtonik@gmail.com>
parents: 4930
diff changeset
21 local `roundup-admin` tool.
eeb9572b0508 doc: Update XML-RPC documentation with example that points to demo
anatoly techtonik <techtonik@gmail.com>
parents: 4930
diff changeset
22
eeb9572b0508 doc: Update XML-RPC documentation with example that points to demo
anatoly techtonik <techtonik@gmail.com>
parents: 4930
diff changeset
23 By default XML-RPC is accessible from ``/xmlrpc`` endpoint:
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
24
4936
eeb9572b0508 doc: Update XML-RPC documentation with example that points to demo
anatoly techtonik <techtonik@gmail.com>
parents: 4930
diff changeset
25 http://username:password@localhost:8000/xmlrpc
eeb9572b0508 doc: Update XML-RPC documentation with example that points to demo
anatoly techtonik <techtonik@gmail.com>
parents: 4930
diff changeset
26
eeb9572b0508 doc: Update XML-RPC documentation with example that points to demo
anatoly techtonik <techtonik@gmail.com>
parents: 4930
diff changeset
27 For demo tracker the URL would be:
eeb9572b0508 doc: Update XML-RPC documentation with example that points to demo
anatoly techtonik <techtonik@gmail.com>
parents: 4930
diff changeset
28
eeb9572b0508 doc: Update XML-RPC documentation with example that points to demo
anatoly techtonik <techtonik@gmail.com>
parents: 4930
diff changeset
29 http://localhost:8917/demo/xmlrpc
eeb9572b0508 doc: Update XML-RPC documentation with example that points to demo
anatoly techtonik <techtonik@gmail.com>
parents: 4930
diff changeset
30
7472
db58a86aa29d Redo headers. Elevete lack of ssl to caution.
John Rouillard <rouilj@ieee.org>
parents: 6774
diff changeset
31 Enabling XML-RPC
db58a86aa29d Redo headers. Elevete lack of ssl to caution.
John Rouillard <rouilj@ieee.org>
parents: 6774
diff changeset
32 ================
4936
eeb9572b0508 doc: Update XML-RPC documentation with example that points to demo
anatoly techtonik <techtonik@gmail.com>
parents: 4930
diff changeset
33 There are two ways to run the XML-RPC interface:
4678
23de24f57566 issue2550749 - the xmlrpc interface is invoked on content type
rouilj
parents: 4449
diff changeset
34
5879
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
35 through roundup itself
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
36
4678
23de24f57566 issue2550749 - the xmlrpc interface is invoked on content type
rouilj
parents: 4449
diff changeset
37 stand alone roundup-xmlrpc-server
23de24f57566 issue2550749 - the xmlrpc interface is invoked on content type
rouilj
parents: 4449
diff changeset
38
5879
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
39
7472
db58a86aa29d Redo headers. Elevete lack of ssl to caution.
John Rouillard <rouilj@ieee.org>
parents: 6774
diff changeset
40 Through Roundup
5879
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
41 ---------------
7472
db58a86aa29d Redo headers. Elevete lack of ssl to caution.
John Rouillard <rouilj@ieee.org>
parents: 6774
diff changeset
42
5879
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
43 The XML-RPC service is available from the roundup HTTP server under
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
44 /xmlrpc.
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
45
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
46 To enable this set ``enable_xmlrpc`` to ``yes`` in the ``[web]``
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
47 section of the ``config.ini`` file in your tracker.
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
48
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
49 Each user that needs access must include the "Xmlrpc Access" role. To
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
50 add this new permission to the "User" role you should change your
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
51 schema.py to add::
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
52
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
53 db.security.addPermissionToRole('User', 'Xmlrpc Access')
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
54
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
55 This is usually included near where other permissions like "Web Access"
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
56 or "Email Access" are assigned.
4939
47cc50617e19 doc/xmlrpc: Fix headers
anatoly techtonik <techtonik@gmail.com>
parents: 4936
diff changeset
57
7472
db58a86aa29d Redo headers. Elevete lack of ssl to caution.
John Rouillard <rouilj@ieee.org>
parents: 6774
diff changeset
58 Standalone roundup-xmlrpc-server
db58a86aa29d Redo headers. Elevete lack of ssl to caution.
John Rouillard <rouilj@ieee.org>
parents: 6774
diff changeset
59 --------------------------------
db58a86aa29d Redo headers. Elevete lack of ssl to caution.
John Rouillard <rouilj@ieee.org>
parents: 6774
diff changeset
60
db58a86aa29d Redo headers. Elevete lack of ssl to caution.
John Rouillard <rouilj@ieee.org>
parents: 6774
diff changeset
61 Using Roundup to access the xmlrpc interface is preferred. Roundup
5879
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
62 provides better control over who can use the interface.
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5332
diff changeset
63
6026
e2b70d43d0fc Document issues with xmlrpc security of python built in libraries
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
64 The Roundup XML-RPC standalone server must be started before remote
e2b70d43d0fc Document issues with xmlrpc security of python built in libraries
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
65 clients can access the tracker via XML-RPC. ``roundup-xmlrpc-server``
e2b70d43d0fc Document issues with xmlrpc security of python built in libraries
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
66 is installed in the scripts directory alongside ``roundup-server`` and
e2b70d43d0fc Document issues with xmlrpc security of python built in libraries
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
67 ``roundup-admin``. When invoked, the location of the tracker instance
e2b70d43d0fc Document issues with xmlrpc security of python built in libraries
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
68 must be specified.
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
69
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
70 roundup-xmlrpc-server -i ``/path/to/tracker``
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
71
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
72 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
73 ``--port`` switch.
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
74
7472
db58a86aa29d Redo headers. Elevete lack of ssl to caution.
John Rouillard <rouilj@ieee.org>
parents: 6774
diff changeset
75 Security Consideration
db58a86aa29d Redo headers. Elevete lack of ssl to caution.
John Rouillard <rouilj@ieee.org>
parents: 6774
diff changeset
76 ======================
db58a86aa29d Redo headers. Elevete lack of ssl to caution.
John Rouillard <rouilj@ieee.org>
parents: 6774
diff changeset
77
6026
e2b70d43d0fc Document issues with xmlrpc security of python built in libraries
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
78 Both the standalone and embedded roundup XML endpoints used the
e2b70d43d0fc Document issues with xmlrpc security of python built in libraries
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
79 default python XML parser. This parser is know to have security
6370
45e8d10a9609 Update links in documentation
John Rouillard <rouilj@ieee.org>
parents: 6342
diff changeset
80 issues. For details see: https://pypi.org/project/defusedxml/.
6026
e2b70d43d0fc Document issues with xmlrpc security of python built in libraries
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
81 You may wish to use the rest interface which doesn't have the same
e2b70d43d0fc Document issues with xmlrpc security of python built in libraries
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
82 issues. Patches with tests to roundup to use defusedxml are welcome.
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
83
7472
db58a86aa29d Redo headers. Elevete lack of ssl to caution.
John Rouillard <rouilj@ieee.org>
parents: 6774
diff changeset
84 .. caution::
db58a86aa29d Redo headers. Elevete lack of ssl to caution.
John Rouillard <rouilj@ieee.org>
parents: 6774
diff changeset
85
7498
924b07252412 Fix verb agreement, reword.
John Rouillard <rouilj@ieee.org>
parents: 7472
diff changeset
86 The current standalone ``roundup-xmlrpc-server`` implementation
924b07252412 Fix verb agreement, reword.
John Rouillard <rouilj@ieee.org>
parents: 7472
diff changeset
87 does not support SSL. This means that usernames and passwords will
924b07252412 Fix verb agreement, reword.
John Rouillard <rouilj@ieee.org>
parents: 7472
diff changeset
88 be passed in cleartext unless the server is proxied behind
924b07252412 Fix verb agreement, reword.
John Rouillard <rouilj@ieee.org>
parents: 7472
diff changeset
89 another server (such as Apache or lighttpd) that provides SSL.
4939
47cc50617e19 doc/xmlrpc: Fix headers
anatoly techtonik <techtonik@gmail.com>
parents: 4936
diff changeset
90
47cc50617e19 doc/xmlrpc: Fix headers
anatoly techtonik <techtonik@gmail.com>
parents: 4936
diff changeset
91 Client API
7472
db58a86aa29d Redo headers. Elevete lack of ssl to caution.
John Rouillard <rouilj@ieee.org>
parents: 6774
diff changeset
92 ==========
6342
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
93 The server currently implements seven methods/commands. Each method
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
94 requires that the user provide a username and password in the HTTP
6026
e2b70d43d0fc Document issues with xmlrpc security of python built in libraries
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
95 authorization header in order to authenticate the request against the
e2b70d43d0fc Document issues with xmlrpc security of python built in libraries
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
96 tracker.
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
97
3969
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
98 ======= ====================================================================
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
99 Command Description
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
100 ======= ====================================================================
4930
f47c35727b3e Add missing doc for xmlrpc schema (fixes issue2550735)
Cédric Krier <ced@b2ck.com>
parents: 4929
diff changeset
101 schema
f47c35727b3e Add missing doc for xmlrpc schema (fixes issue2550735)
Cédric Krier <ced@b2ck.com>
parents: 4929
diff changeset
102
f47c35727b3e Add missing doc for xmlrpc schema (fixes issue2550735)
Cédric Krier <ced@b2ck.com>
parents: 4929
diff changeset
103 Fetch tracker schema.
f47c35727b3e Add missing doc for xmlrpc schema (fixes issue2550735)
Cédric Krier <ced@b2ck.com>
parents: 4929
diff changeset
104
3969
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
105 list arguments: *classname, [property_name]*
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
106
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
107 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
108 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
109 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
110 property will be used.
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
111
3969
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
112 display arguments: *designator, [property_1, ..., property_N]*
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
113
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
114 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
115 (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
116 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
117 specified.
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
118
3969
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
119 create arguments: *classname, arg_1 ... arg_N*
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
120
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
121 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
122 ``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
123 name=value pairs (e.g. ``status='3'``).
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
124
3969
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
125 set arguments: *designator, arg_1 ... arg_N*
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
126
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
127 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
128 ``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
129 ``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
130
4449
3f251efd5f48 Add "lookup" method to xmlrpc interface (Ralf Schlatterbeck)
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4257
diff changeset
131 lookup arguments: *classname, key_value*
3f251efd5f48 Add "lookup" method to xmlrpc interface (Ralf Schlatterbeck)
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4257
diff changeset
132
3f251efd5f48 Add "lookup" method to xmlrpc interface (Ralf Schlatterbeck)
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4257
diff changeset
133 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
134 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
135 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
136
4257
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
137 filter arguments: *classname, list or None, attributes*
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
138
4929
57a482110a24 doc: Link XMLRPC `filter` doc to User Guide chapter about querying
anatoly techtonik <techtonik@gmail.com>
parents: 4916
diff changeset
139 ``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
140 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
141 instantiating the ServerProxy). The ``attributes`` are given as a
6342
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
142 dictionary of name value pairs to search for. See also
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
143 :ref:`query-tracker`.
3969
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
144 ======= ====================================================================
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
145
7472
db58a86aa29d Redo headers. Elevete lack of ssl to caution.
John Rouillard <rouilj@ieee.org>
parents: 6774
diff changeset
146 Sample Python Client
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
147 ====================
5219
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
148
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
149 This client will work if you turn off the x-requested-with header and
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
150 the only CSRF header check you require is the HTTP host header::
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
151
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
152 >>> import xmlrpclib
4936
eeb9572b0508 doc: Update XML-RPC documentation with example that points to demo
anatoly techtonik <techtonik@gmail.com>
parents: 4930
diff changeset
153 >>> roundup_server = xmlrpclib.ServerProxy('http://admin:admin@localhost:8917/demo/xmlrpc', allow_none=True)
4930
f47c35727b3e Add missing doc for xmlrpc schema (fixes issue2550735)
Cédric Krier <ced@b2ck.com>
parents: 4929
diff changeset
154 >>> roundup_server.schema()
f47c35727b3e Add missing doc for xmlrpc schema (fixes issue2550735)
Cédric Krier <ced@b2ck.com>
parents: 4929
diff changeset
155 {'user': [['username', '<roundup.hyperdb.String>'], ...], 'issue': [...]}
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
156 >>> roundup_server.list('user')
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
157 ['admin', 'anonymous', 'demo']
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
158 >>> roundup_server.list('issue', 'id')
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
159 ['1']
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
160 >>> roundup_server.display('issue1')
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
161 {'assignedto' : None, 'files' : [], 'title' = 'yes, ..... }
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
162 >>> roundup_server.display('issue1', 'priority', 'status')
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
163 {'priority' : '1', 'status' : '2'}
3951
53b922e0d2b7 typo in docs for xmlrpc
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3950
diff changeset
164 >>> roundup_server.set('issue1', 'status=3')
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
165 >>> roundup_server.display('issue1', 'status')
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
166 {'status' : '3' }
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
167 >>> 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
168 '2'
4257
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
169 >>> roundup_server.filter('user',None,{'username':'adm'})
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
170 ['1']
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
171 >>> 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
172 ['1']
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
173 >>> roundup_server.filter('user',['2'],{'username':'adm'})
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
174 []
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
175 >>> roundup_server.filter('user',[],{'username':'adm'})
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
176 []
4449
3f251efd5f48 Add "lookup" method to xmlrpc interface (Ralf Schlatterbeck)
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4257
diff changeset
177 >>> roundup_server.lookup('user','admin')
3f251efd5f48 Add "lookup" method to xmlrpc interface (Ralf Schlatterbeck)
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4257
diff changeset
178 '1'
5219
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
179
7472
db58a86aa29d Redo headers. Elevete lack of ssl to caution.
John Rouillard <rouilj@ieee.org>
parents: 6774
diff changeset
180 Advanced Python Client Adding anti-csrf Headers
5298
6efa6d44c27a Add doc for xmlrpc changes and errors related to anti-csrf protections.
John Rouillard <rouilj@ieee.org>
parents: 5248
diff changeset
181 ===============================================
6efa6d44c27a Add doc for xmlrpc changes and errors related to anti-csrf protections.
John Rouillard <rouilj@ieee.org>
parents: 5248
diff changeset
182
5219
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
183 The one below adds Referer and X-Requested-With headers so it can pass
5220
14d8f61e6ef2 Reimplemented anti-csrf measures by raising exceptions rather than
John Rouillard <rouilj@ieee.org>
parents: 5219
diff changeset
184 stronger CSRF detection methods. It also generates a fault message
14d8f61e6ef2 Reimplemented anti-csrf measures by raising exceptions rather than
John Rouillard <rouilj@ieee.org>
parents: 5219
diff changeset
185 from the server and reports it. Note if you are using http rather than
14d8f61e6ef2 Reimplemented anti-csrf measures by raising exceptions rather than
John Rouillard <rouilj@ieee.org>
parents: 5219
diff changeset
186 https, replace xmlrpclib.SafeTransport with xmlrpclib.Transport::
5219
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
187
6342
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
188 try:
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
189 from xmlrpc import client as xmlrpclib # python 3
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
190 except ImportError:
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
191 import xmlrpclib # python 2
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
192
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
193 hostname="localhost"
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
194 path="/demo"
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
195 user_pw="admin:admin"
5219
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
196
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
197 class SpecialTransport(xmlrpclib.SafeTransport):
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
198
6342
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
199 def send_content(self, connection, request_body):
5219
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
200
6342
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
201 connection.putheader("Referer", "https://%s%s/"%(hostname, path))
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
202 connection.putheader("Origin", "https://%s"%hostname)
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
203 connection.putheader("X-Requested-With", "XMLHttpRequest")
5219
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
204
6342
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
205 connection.putheader("Content-Type", "text/xml")
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
206 connection.putheader("Content-Length", str(len(request_body)))
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
207 connection.endheaders()
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
208 if request_body:
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
209 connection.send(request_body)
5219
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
210
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
211 roundup_server = xmlrpclib.ServerProxy(
6342
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
212 'https://%s@%s%s/xmlrpc'%(user_pw,hostname,path),
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
213 transport=SpecialTransport(),
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
214 verbose=False,
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
215 allow_none=True)
5219
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
216
5332
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5298
diff changeset
217 print(roundup_server.schema())
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5298
diff changeset
218 print(roundup_server.display('user2', 'username'))
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5298
diff changeset
219 print(roundup_server.display('issue1', 'status'))
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5298
diff changeset
220 print(roundup_server.filter('user',['1','2','3'],{'username':'demo'}))
5220
14d8f61e6ef2 Reimplemented anti-csrf measures by raising exceptions rather than
John Rouillard <rouilj@ieee.org>
parents: 5219
diff changeset
221
6342
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
222 # this will fail with a fault
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
223 try:
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
224 print(roundup_server.filter('usr',['0','2','3'],{'username':'demo'}))
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
225 except Exception as msg:
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
226 print(msg)
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
227
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
228 modify this script replacing the hostname, path and user_pw with those
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
229 for your tracker.
Roundup Issue Tracker: http://roundup-tracker.org/