Mercurial > p > roundup > code

annotate doc/xmlrpc.txt @ 8168:3f0f4746dc7e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
issue2551370 - prefix session cookie with __Secure- over https Limit use of roundup session cookie to HTTPS protocol by adding __Secure- prefix. Automatic testing includes http behavior only. Https behavious has been manually tested only. Need to be able to spin up an https server using wsgiref to test https behavior in CI. issue 2551373 opened to track automatic testing of https behavior.
author John Rouillard <rouilj@ieee.org>
date Tue, 26 Nov 2024 17:11:13 -0500
parents e34b69d75ff7
children 57325fea9982
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
7734
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
97 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
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
7734
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
110 .. table::
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
111 :class: valign-top
4930
f47c35727b3e Add missing doc for xmlrpc schema (fixes issue2550735)
Cédric Krier <ced@b2ck.com>
parents: 4929
diff changeset
112
7734
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
113 ======= ===================================================================
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
114 Command Description
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
115 ======= ===================================================================
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
116 schema Fetch tracker schema.
4930
f47c35727b3e Add missing doc for xmlrpc schema (fixes issue2550735)
Cédric Krier <ced@b2ck.com>
parents: 4929
diff changeset
117
7734
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
118 list arguments: *classname, [property_name]*
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
119
7734
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
120 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
121 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
122 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
123 property will be used.
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
124
7734
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
125 display arguments: *designator, [property_1, ..., property_N]*
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
126
7734
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
127 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
128 (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
129 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
130 be specified.
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
131
7734
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
132 create arguments: *classname, arg_1 ... arg_N*
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
133
7734
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
134 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
135 ``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
136 name=value pairs (e.g. ``status='3'``).
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
137
7734
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
138 set arguments: *designator, arg_1 ... arg_N*
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
139
7734
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
140 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
141 ``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
142 ``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
143
7734
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
144 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
145
7734
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
146 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
147 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
148 attribute and id for the given classname.
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
149
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
150 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
151
7734
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
152 ``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
153 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
154 instantiating the ServerProxy). The ``attributes`` are given
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
155 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
156 :ref:`query-tracker`.
e34b69d75ff7 doc: more table call alignment; fix formatting
John Rouillard <rouilj@ieee.org>
parents: 7611
diff changeset
157 ======= ===================================================================
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
158
7472
db58a86aa29d Redo headers. Elevete lack of ssl to caution.
John Rouillard <rouilj@ieee.org>
parents: 6774
diff changeset
159 Sample Python Client
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
160 ====================
5219
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
161
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
162 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
163 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
164
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
165 >>> import xmlrpclib
4936
eeb9572b0508 doc: Update XML-RPC documentation with example that points to demo
anatoly techtonik <techtonik@gmail.com>
parents: 4930
diff changeset
166 >>> 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
167 >>> roundup_server.schema()
f47c35727b3e Add missing doc for xmlrpc schema (fixes issue2550735)
Cédric Krier <ced@b2ck.com>
parents: 4929
diff changeset
168 {'user': [['username', '<roundup.hyperdb.String>'], ...], 'issue': [...]}
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
169 >>> roundup_server.list('user')
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
170 ['admin', 'anonymous', 'demo']
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
171 >>> roundup_server.list('issue', 'id')
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
172 ['1']
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
173 >>> roundup_server.display('issue1')
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
174 {'assignedto' : None, 'files' : [], 'title' = 'yes, ..... }
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
175 >>> roundup_server.display('issue1', 'priority', 'status')
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
176 {'priority' : '1', 'status' : '2'}
3951
53b922e0d2b7 typo in docs for xmlrpc
Justus Pendleton <jpend@users.sourceforge.net>
parents: 3950
diff changeset
177 >>> roundup_server.set('issue1', 'status=3')
3950
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
178 >>> roundup_server.display('issue1', 'status')
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
179 {'status' : '3' }
257b4eab3bb2 Documentation for the XML-RPC interface
Justus Pendleton <jpend@users.sourceforge.net>
parents:
diff changeset
180 >>> 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
181 '2'
4257
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
182 >>> roundup_server.filter('user',None,{'username':'adm'})
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
183 ['1']
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
184 >>> 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
185 ['1']
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
186 >>> roundup_server.filter('user',['2'],{'username':'adm'})
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
187 []
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
188 >>> roundup_server.filter('user',[],{'username':'adm'})
a70dbbc7f967 Document filter method of xmlrpc interface
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 3969
diff changeset
189 []
4449
3f251efd5f48 Add "lookup" method to xmlrpc interface (Ralf Schlatterbeck)
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4257
diff changeset
190 >>> roundup_server.lookup('user','admin')
3f251efd5f48 Add "lookup" method to xmlrpc interface (Ralf Schlatterbeck)
Ralf Schlatterbeck <schlatterbeck@users.sourceforge.net>
parents: 4257
diff changeset
191 '1'
5219
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
192
7472
db58a86aa29d Redo headers. Elevete lack of ssl to caution.
John Rouillard <rouilj@ieee.org>
parents: 6774
diff changeset
193 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
194 ===============================================
6efa6d44c27a Add doc for xmlrpc changes and errors related to anti-csrf protections.
John Rouillard <rouilj@ieee.org>
parents: 5248
diff changeset
195
5219
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
196 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
197 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
198 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
199 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
200
6342
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
201 try:
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
202 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
203 except ImportError:
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
204 import xmlrpclib # python 2
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
205
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
206 hostname="localhost"
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
207 path="/demo"
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
208 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
209
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
210 class SpecialTransport(xmlrpclib.SafeTransport):
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
211
6342
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
212 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
213
6342
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
214 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
215 connection.putheader("Origin", "https://%s"%hostname)
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
216 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
217
6342
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
218 connection.putheader("Content-Type", "text/xml")
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
219 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
220 connection.endheaders()
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
221 if request_body:
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
222 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
223
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
224 roundup_server = xmlrpclib.ServerProxy(
6342
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
225 '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
226 transport=SpecialTransport(),
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
227 verbose=False,
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
228 allow_none=True)
5219
ade4bbc2716d Update the xmlrpc documentation for use with the CSRF defenses.
John Rouillard <rouilj@ieee.org>
parents: 4939
diff changeset
229
5332
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5298
diff changeset
230 print(roundup_server.schema())
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('user2', 'username'))
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('issue1', 'status'))
d0689aaa83db Applied patch 0038 from issue2550960 to upgrade code examples in
John Rouillard <rouilj@ieee.org>
parents: 5298
diff changeset
233 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
234
6342
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
235 # this will fail with a fault
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
236 try:
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
237 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
238 except Exception as msg:
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
239 print(msg)
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
240
31bac6f2dd8b Update advanced script to python3; other doc updates
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
241 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
242 for your tracker.
Roundup Issue Tracker: http://roundup-tracker.org/