Mercurial > p > roundup > code

annotate doc/xmlrpc.txt @ 8408:e882a5d52ae5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
refactor: move RateLimitExceeded to roundup.cgi.exceptions RateLimitExceeded is an HTTP exception that raises code 429. Move it to roundup.cgi.exceptions where all the other exceptions that result in http status codes are located. Also make it inherit from HTTPException since it is one. Also add docstrings for all HTTP exceptions and order HTTPExceptions by status code. BREAKING CHANGE: if somebody is importing RateLimitExceeded they will need to change their import. I consider it unlikely anybody is using RateLimitExceeded. Detectors and extensions are unlikely to raise RateLimitExceeded. So I am leaving it out of the upgrading doc. Just doc in change log.
author John Rouillard <rouilj@ieee.org>
date Sun, 10 Aug 2025 21:27:06 -0400
parents 57325fea9982
children
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
8237
57325fea9982 issue2551116 - Replace xmlrpclib (xmlrpc.client) with defusedxml.
John Rouillard <rouilj@ieee.org>
parents: 7734
diff changeset
82 issues. If you install defusedxml, it will be automatically used to add
57325fea9982 issue2551116 - Replace xmlrpclib (xmlrpc.client) with defusedxml.
John Rouillard <rouilj@ieee.org>
parents: 7734
diff changeset
83 some additional protection.
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
84
7472
db58a86aa29d Redo headers. Elevete lack of ssl to caution.
John Rouillard <rouilj@ieee.org>
parents: 6774
diff changeset
85 .. caution::
db58a86aa29d Redo headers. Elevete lack of ssl to caution.
John Rouillard <rouilj@ieee.org>
parents: 6774
diff changeset
86
7498
924b07252412 Fix verb agreement, reword.
John Rouillard <rouilj@ieee.org>
parents: 7472
diff changeset
87 The current standalone ``roundup-xmlrpc-server`` implementation
924b07252412 Fix verb agreement, reword.
John Rouillard <rouilj@ieee.org>
parents: 7472
diff changeset
88 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
89 be passed in cleartext unless the server is proxied behind
924b07252412 Fix verb agreement, reword.
John Rouillard <rouilj@ieee.org>
parents: 7472
diff changeset
90 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
91
7556
273c8c2b5042 fix(api): - issue2551063 - Rest/Xmlrpc interfaces needs failed login protection.
John Rouillard <rouilj@ieee.org>
parents: 7498
diff changeset
92 Rate Limiting Failed Logins
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
273c8c2b5042 fix(api): - issue2551063 - Rest/Xmlrpc interfaces needs failed login protection.
John Rouillard <rouilj@ieee.org>
parents: 7498
diff changeset
95 See the `rest documentation
273c8c2b5042 fix(api): - issue2551063 - Rest/Xmlrpc interfaces needs failed login protection.
John Rouillard <rouilj@ieee.org>
parents: 7498
diff changeset
96 <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
97 logins on the API. There is no login rate limiting for the standalone
7734
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
98 roundup-xmlrpc-server. Login rate limiting is only for the ``/xmlrpc``
7611
c3a7b1aa06cf docs: clarify no login rate limit for roundup-xmlrpc-server
John Rouillard <rouilj@ieee.org>
parents: 7556
diff changeset
99 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
100
c3a7b1aa06cf docs: clarify no login rate limit for roundup-xmlrpc-server
John Rouillard <rouilj@ieee.org>
parents: 7556
diff changeset
101 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
102 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
103
4939
47cc50617e19 doc/xmlrpc: Fix headers
anatoly techtonik <techtonik@gmail.com>
parents: 4936
diff changeset
104 Client API
7472
db58a86aa29d Redo headers. Elevete lack of ssl to caution.
John Rouillard <rouilj@ieee.org>
parents: 6774
diff changeset
105 ==========
6342
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
106 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
107 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
108 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
109 tracker.
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
110
7734
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
111 .. table::
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
112 :class: valign-top
4930
f47c35727b3e Add missing doc for xmlrpc schema (fixes issue2550735)
Cédric Krier <ced@b2ck.com>
parents: 4929
diff changeset
113
7734
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
114 ======= ===================================================================
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
115 Command Description
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
116 ======= ===================================================================
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
117 schema Fetch tracker schema.
4930
f47c35727b3e Add missing doc for xmlrpc schema (fixes issue2550735)
Cédric Krier <ced@b2ck.com>
parents: 4929
diff changeset
118
7734
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
119 list arguments: *classname, [property_name]*
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
120
7734
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
121 List all elements of a given ``classname``. If ``property_name``
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
122 is specified, that is the property that will be displayed for each
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
123 element. If ``property_name`` is not specified the default label
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
124 property will be used.
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
125
7734
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
126 display arguments: *designator, [property_1, ..., property_N]*
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
127
7734
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
128 Display a single item in the tracker as specified by ``designator``
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
129 (e.g. issue20 or user5). The default is to display all properties
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
130 for the item. Alternatively, a list of properties to display can
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
131 be specified.
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
132
7734
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
133 create arguments: *classname, arg_1 ... arg_N*
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
134
7734
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
135 Create a new instance of ``classname`` with ``arg_1`` through
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
136 ``arg_N`` as the values of the new instance. The arguments are
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
137 name=value pairs (e.g. ``status='3'``).
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
138
7734
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
139 set arguments: *designator, arg_1 ... arg_N*
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
140
7734
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
141 Set the values of an existing item in the tracker as specified by
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
142 ``designator``. The new values are specified in ``arg_1`` through
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
143 ``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
144
7734
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
145 lookup arguments: *classname, key_value*
4449
3f251efd5f48 Add "lookup" method to xmlrpc interface (Ralf Schlatterbeck)
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4257
diff changeset
146
7734
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
147 looks up the key_value for the given class. The class needs to
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
148 have a key and the user needs search permission on the key
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
149 attribute and id for the given classname.
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
150
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
151 filter arguments: *classname, list or None, attributes*
4449
3f251efd5f48 Add "lookup" method to xmlrpc interface (Ralf Schlatterbeck)
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4257
diff changeset
152
7734
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
153 ``list`` is a list of ids to filter. It can be set to None to
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
154 run filter over all values (requires ``allow_none=True`` when
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
155 instantiating the ServerProxy). The ``attributes`` are given
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
156 as a dictionary of name value pairs to search for. See also
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
157 :ref:`query-tracker`.
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
158 ======= ===================================================================
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
159
7472
db58a86aa29d Redo headers. Elevete lack of ssl to caution.
John Rouillard <rouilj@ieee.org>
parents: 6774
diff changeset
160 Sample Python Client
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
161 ====================
5219
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
162
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
163 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
164 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
165
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
166 >>> import xmlrpclib
4936
eeb9572b0508 doc: Update XML-RPC documentation with example that points to demo
anatoly techtonik <techtonik@gmail.com>
parents: 4930
diff changeset
167 >>> 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
168 >>> roundup_server.schema()
f47c35727b3e Add missing doc for xmlrpc schema (fixes issue2550735)
Cédric Krier <ced@b2ck.com>
parents: 4929
diff changeset
169 {'user': [['username', '<roundup.hyperdb.String>'], ...], 'issue': [...]}
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
170 >>> roundup_server.list('user')
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
171 ['admin', 'anonymous', 'demo']
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
172 >>> roundup_server.list('issue', 'id')
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
173 ['1']
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
174 >>> roundup_server.display('issue1')
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
175 {'assignedto' : None, 'files' : [], 'title' = 'yes, ..... }
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
176 >>> roundup_server.display('issue1', 'priority', 'status')
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
177 {'priority' : '1', 'status' : '2'}
3951
53b922e0d2b7 typo in docs for xmlrpc
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3950
diff changeset
178 >>> roundup_server.set('issue1', 'status=3')
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
179 >>> roundup_server.display('issue1', 'status')
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
180 {'status' : '3' }
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
181 >>> 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
182 '2'
4257
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
183 >>> roundup_server.filter('user',None,{'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',['1','2'],{'username':'adm'})
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
186 ['1']
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
187 >>> roundup_server.filter('user',['2'],{'username':'adm'})
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
188 []
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
189 >>> roundup_server.filter('user',[],{'username':'adm'})
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
190 []
4449
3f251efd5f48 Add "lookup" method to xmlrpc interface (Ralf Schlatterbeck)
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4257
diff changeset
191 >>> roundup_server.lookup('user','admin')
3f251efd5f48 Add "lookup" method to xmlrpc interface (Ralf Schlatterbeck)
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4257
diff changeset
192 '1'
5219
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
193
7472
db58a86aa29d Redo headers. Elevete lack of ssl to caution.
John Rouillard <rouilj@ieee.org>
parents: 6774
diff changeset
194 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
195 ===============================================
6efa6d44c27a Add doc for xmlrpc changes and errors related to anti-csrf protections.
John Rouillard <rouilj@ieee.org>
parents: 5248
diff changeset
196
5219
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
197 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
198 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
199 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
200 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
201
6342
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
202 try:
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
203 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
204 except ImportError:
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
205 import xmlrpclib # python 2
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
206
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
207 hostname="localhost"
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
208 path="/demo"
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
209 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
210
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
211 class SpecialTransport(xmlrpclib.SafeTransport):
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 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
214
6342
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
215 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
216 connection.putheader("Origin", "https://%s"%hostname)
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
217 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
218
6342
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
219 connection.putheader("Content-Type", "text/xml")
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
220 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
221 connection.endheaders()
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
222 if request_body:
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
223 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
224
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
225 roundup_server = xmlrpclib.ServerProxy(
6342
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
226 '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
227 transport=SpecialTransport(),
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
228 verbose=False,
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
229 allow_none=True)
5219
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
230
5332
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5298
diff changeset
231 print(roundup_server.schema())
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5298
diff changeset
232 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
233 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
234 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
235
6342
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
236 # this will fail with a fault
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
237 try:
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
238 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
239 except Exception as msg:
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
240 print(msg)
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
241
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
242 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
243 for your tracker.
Roundup Issue Tracker: http://roundup-tracker.org/