Mercurial > p > roundup > code

annotate doc/xmlrpc.txt @ 7667:08e4399c3ae4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: document the messages generated from import/export The numbers reported when exporting/importing don't make sense unless you know how they are generated and used. Document that. Norbert Schlemmer asked about it while debugging an import issue with postgresql. So document it since I did the work.
author John Rouillard <rouilj@ieee.org>
date Thu, 19 Oct 2023 14:07:56 -0400
parents c3a7b1aa06cf
children e34b69d75ff7
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
7556
273c8c2b5042 fix(api): - issue2551063 - Rest/Xmlrpc interfaces needs failed login protection.
John Rouillard <rouilj@ieee.org>
parents: 7498
diff changeset
91 Rate Limiting Failed Logins
273c8c2b5042 fix(api): - issue2551063 - Rest/Xmlrpc interfaces needs failed login protection.
John Rouillard <rouilj@ieee.org>
parents: 7498
diff changeset
92 ---------------------------
273c8c2b5042 fix(api): - issue2551063 - Rest/Xmlrpc interfaces needs failed login protection.
John Rouillard <rouilj@ieee.org>
parents: 7498
diff changeset
93
273c8c2b5042 fix(api): - issue2551063 - Rest/Xmlrpc interfaces needs failed login protection.
John Rouillard <rouilj@ieee.org>
parents: 7498
diff changeset
94 See the `rest documentation
273c8c2b5042 fix(api): - issue2551063 - Rest/Xmlrpc interfaces needs failed login protection.
John Rouillard <rouilj@ieee.org>
parents: 7498
diff changeset
95 <rest.html#rate-limiting-api-failed-logins>`_ for rate limiting failed
7611
c3a7b1aa06cf docs: clarify no login rate limit for roundup-xmlrpc-server
John Rouillard <rouilj@ieee.org>
parents: 7556
diff changeset
96 logins on the API. There is no login rate limiting for the standalone
c3a7b1aa06cf docs: clarify no login rate limit for roundup-xmlrpc-server
John Rouillard <rouilj@ieee.org>
parents: 7556
diff changeset
97 roundup-xmlrpc-server. Login rate limiting is only for the `/xmlrpc``
c3a7b1aa06cf docs: clarify no login rate limit for roundup-xmlrpc-server
John Rouillard <rouilj@ieee.org>
parents: 7556
diff changeset
98 endpoint when the Roundup server is used.
c3a7b1aa06cf docs: clarify no login rate limit for roundup-xmlrpc-server
John Rouillard <rouilj@ieee.org>
parents: 7556
diff changeset
99
c3a7b1aa06cf docs: clarify no login rate limit for roundup-xmlrpc-server
John Rouillard <rouilj@ieee.org>
parents: 7556
diff changeset
100 The XML-RPC uses the same method as the REST API.
7556
273c8c2b5042 fix(api): - issue2551063 - Rest/Xmlrpc interfaces needs failed login protection.
John Rouillard <rouilj@ieee.org>
parents: 7498
diff changeset
101 Rate limiting is shared between the XMLRPC and REST APIs.
273c8c2b5042 fix(api): - issue2551063 - Rest/Xmlrpc interfaces needs failed login protection.
John Rouillard <rouilj@ieee.org>
parents: 7498
diff changeset
102
4939
47cc50617e19 doc/xmlrpc: Fix headers
anatoly techtonik <techtonik@gmail.com>
parents: 4936
diff changeset
103 Client API
7472
db58a86aa29d Redo headers. Elevete lack of ssl to caution.
John Rouillard <rouilj@ieee.org>
parents: 6774
diff changeset
104 ==========
6342
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
105 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
106 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
107 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
108 tracker.
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
109
3969
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
110 ======= ====================================================================
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
111 Command Description
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
112 ======= ====================================================================
4930
f47c35727b3e Add missing doc for xmlrpc schema (fixes issue2550735)
Cédric Krier <ced@b2ck.com>
parents: 4929
diff changeset
113 schema
f47c35727b3e Add missing doc for xmlrpc schema (fixes issue2550735)
Cédric Krier <ced@b2ck.com>
parents: 4929
diff changeset
114
f47c35727b3e Add missing doc for xmlrpc schema (fixes issue2550735)
Cédric Krier <ced@b2ck.com>
parents: 4929
diff changeset
115 Fetch tracker schema.
f47c35727b3e Add missing doc for xmlrpc schema (fixes issue2550735)
Cédric Krier <ced@b2ck.com>
parents: 4929
diff changeset
116
3969
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
117 list arguments: *classname, [property_name]*
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
118
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
119 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
120 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
121 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
122 property will be used.
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
123
3969
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
124 display arguments: *designator, [property_1, ..., property_N]*
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
125
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
126 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
127 (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
128 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
129 specified.
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
130
3969
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
131 create arguments: *classname, arg_1 ... arg_N*
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
132
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
133 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
134 ``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
135 name=value pairs (e.g. ``status='3'``).
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
136
3969
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
137 set arguments: *designator, arg_1 ... arg_N*
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
138
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
139 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
140 ``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
141 ``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
142
4449
3f251efd5f48 Add "lookup" method to xmlrpc interface (Ralf Schlatterbeck)
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4257
diff changeset
143 lookup arguments: *classname, key_value*
3f251efd5f48 Add "lookup" method to xmlrpc interface (Ralf Schlatterbeck)
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4257
diff changeset
144
3f251efd5f48 Add "lookup" method to xmlrpc interface (Ralf Schlatterbeck)
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4257
diff changeset
145 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
146 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
147 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
148
4257
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
149 filter arguments: *classname, list or None, attributes*
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
150
4929
57a482110a24 doc: Link XMLRPC `filter` doc to User Guide chapter about querying
anatoly techtonik <techtonik@gmail.com>
parents: 4916
diff changeset
151 ``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
152 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
153 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
154 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
155 :ref:`query-tracker`.
3969
905faf52a51f fix mysql breakage in 1.4.2
Richard Jones <richard@users.sourceforge.net>
parents: 3951
diff changeset
156 ======= ====================================================================
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
157
7472
db58a86aa29d Redo headers. Elevete lack of ssl to caution.
John Rouillard <rouilj@ieee.org>
parents: 6774
diff changeset
158 Sample Python Client
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
159 ====================
5219
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
160
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
161 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
162 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
163
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
164 >>> import xmlrpclib
4936
eeb9572b0508 doc: Update XML-RPC documentation with example that points to demo
anatoly techtonik <techtonik@gmail.com>
parents: 4930
diff changeset
165 >>> 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
166 >>> roundup_server.schema()
f47c35727b3e Add missing doc for xmlrpc schema (fixes issue2550735)
Cédric Krier <ced@b2ck.com>
parents: 4929
diff changeset
167 {'user': [['username', '<roundup.hyperdb.String>'], ...], 'issue': [...]}
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
168 >>> roundup_server.list('user')
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
169 ['admin', 'anonymous', 'demo']
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
170 >>> roundup_server.list('issue', 'id')
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
171 ['1']
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
172 >>> roundup_server.display('issue1')
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
173 {'assignedto' : None, 'files' : [], 'title' = 'yes, ..... }
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
174 >>> roundup_server.display('issue1', 'priority', 'status')
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
175 {'priority' : '1', 'status' : '2'}
3951
53b922e0d2b7 typo in docs for xmlrpc
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3950
diff changeset
176 >>> roundup_server.set('issue1', 'status=3')
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
177 >>> roundup_server.display('issue1', 'status')
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
178 {'status' : '3' }
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
179 >>> 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
180 '2'
4257
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
181 >>> roundup_server.filter('user',None,{'username':'adm'})
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
182 ['1']
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
183 >>> 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
184 ['1']
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
185 >>> roundup_server.filter('user',['2'],{'username':'adm'})
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
186 []
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
187 >>> roundup_server.filter('user',[],{'username':'adm'})
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
188 []
4449
3f251efd5f48 Add "lookup" method to xmlrpc interface (Ralf Schlatterbeck)
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4257
diff changeset
189 >>> roundup_server.lookup('user','admin')
3f251efd5f48 Add "lookup" method to xmlrpc interface (Ralf Schlatterbeck)
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4257
diff changeset
190 '1'
5219
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
191
7472
db58a86aa29d Redo headers. Elevete lack of ssl to caution.
John Rouillard <rouilj@ieee.org>
parents: 6774
diff changeset
192 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
193 ===============================================
6efa6d44c27a Add doc for xmlrpc changes and errors related to anti-csrf protections.
John Rouillard <rouilj@ieee.org>
parents: 5248
diff changeset
194
5219
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
195 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
196 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
197 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
198 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
199
6342
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
200 try:
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
201 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
202 except ImportError:
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
203 import xmlrpclib # python 2
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
204
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
205 hostname="localhost"
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
206 path="/demo"
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
207 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
208
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
209 class SpecialTransport(xmlrpclib.SafeTransport):
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
210
6342
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
211 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
212
6342
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
213 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
214 connection.putheader("Origin", "https://%s"%hostname)
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
215 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
216
6342
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
217 connection.putheader("Content-Type", "text/xml")
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
218 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
219 connection.endheaders()
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
220 if request_body:
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
221 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
222
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
223 roundup_server = xmlrpclib.ServerProxy(
6342
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
224 '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
225 transport=SpecialTransport(),
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
226 verbose=False,
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
227 allow_none=True)
5219
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
228
5332
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5298
diff changeset
229 print(roundup_server.schema())
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5298
diff changeset
230 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
231 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
232 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
233
6342
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
234 # this will fail with a fault
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
235 try:
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
236 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
237 except Exception as msg:
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
238 print(msg)
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
239
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
240 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
241 for your tracker.
Roundup Issue Tracker: http://roundup-tracker.org/