Mercurial > p > roundup > code

annotate doc/rest.txt @ 8563:909cf30c01c1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: rename input in examples to input_payload the variable input shadows the built-in function input().
author John Rouillard <rouilj@ieee.org>
date Wed, 08 Apr 2026 22:20:06 -0400
parents 1ffa1f42e1da
children e4191aa7b402
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: 6539
diff changeset
1 .. meta::
6774
e7b4ad2c57ac landmarks, skiplink, remove bad attrs, autocomplete search
John Rouillard <rouilj@ieee.org>
parents: 6765
diff changeset
2 :description:
6586
24e2eeb2ed9a Add meta description to some doc pages.
John Rouillard <rouilj@ieee.org>
parents: 6539
diff changeset
3 Documentation on the RESTful interface to the Roundup Issue
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
4 Tracker. Enable REST access, endpoints, methods,
7282
f86a4a712f1f update metadata for rest.txt html page.
John Rouillard <rouilj@ieee.org>
parents: 7155
diff changeset
5 authentication, discovery.
6586
24e2eeb2ed9a Add meta description to some doc pages.
John Rouillard <rouilj@ieee.org>
parents: 6539
diff changeset
6
6167
81ae33038ec5 more index entries.
John Rouillard <rouilj@ieee.org>
parents: 6166
diff changeset
7 .. index:: pair: api; Representational state transfer
81ae33038ec5 more index entries.
John Rouillard <rouilj@ieee.org>
parents: 6166
diff changeset
8 pair: api; rest
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
9
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
10 ====================
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
11 REST API for Roundup
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
12 ====================
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
13
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
14 .. contents::
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
15 :local:
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
16 :depth: 3
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
17
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
18 Introduction
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
19 ============
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
20
7825
ee0062411160 doc: remove unneeded word.
John Rouillard <rouilj@ieee.org>
parents: 7809
diff changeset
21 After the 1.6.0 Release, a REST-API developed in 2015 during a
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
22 Google Summer of Code (GSOC) by Chau Nguyen, supervised by Ezio
7600
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
23 Melotti was integrated. The code was updated by Ralf Schlatterbeck and
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
24 John Rouillard to address some limitations and incorporate essential
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
25 features for a single page web application, such as etag support,
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
26 pagination, and field embedding, among others.
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
27
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
28 Enabling the REST API
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
29 =====================
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
30
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
31 The REST API can be disabled in the ``[web]`` section of ``config.ini``
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
32 via the variable ``enable_rest`` which is ``yes`` by default.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
33
5879
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5878
diff changeset
34 Users have to be authorized to use the rest api. The user must have
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5878
diff changeset
35 "Rest Access" permission. To add this to the "User" role change
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5878
diff changeset
36 schema.py to add::
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5878
diff changeset
37
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5878
diff changeset
38 db.security.addPermissionToRole('User', 'Rest Access')
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5878
diff changeset
39
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5878
diff changeset
40 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: 5878
diff changeset
41 or "Email Access" are assigned.
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5878
diff changeset
42
5901
a592e3156134 Added more verbage on "Rest Access" permission and reworked search docs.
John Rouillard <rouilj@ieee.org>
parents: 5898
diff changeset
43 You could also create a new role "rest" and assign the "Rest Access"
6373
3dcbe44eb1cd Fix thinko add role not permission to users.
John Rouillard <rouilj@ieee.org>
parents: 6315
diff changeset
44 permission to that role and then just add the "rest" role to
5901
a592e3156134 Added more verbage on "Rest Access" permission and reworked search docs.
John Rouillard <rouilj@ieee.org>
parents: 5898
diff changeset
45 those users who should have access.
a592e3156134 Added more verbage on "Rest Access" permission and reworked search docs.
John Rouillard <rouilj@ieee.org>
parents: 5898
diff changeset
46
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
47 The REST api is reached via the ``/rest/`` endpoint of the tracker
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
48 URL. Partial URLs paths below (not starting with https) will have
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
49 /rest removed for brevity.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
50
5826
8e17c34a5cf0 issue2551048. Document WEB_SECRET_KEY in config.ini.
John Rouillard <rouilj@ieee.org>
parents: 5824
diff changeset
51 Make sure that the ``secret_key`` option is defined in the
8e17c34a5cf0 issue2551048. Document WEB_SECRET_KEY in config.ini.
John Rouillard <rouilj@ieee.org>
parents: 5824
diff changeset
52 ``[web]`` section of your tracker's ``config.ini``. Following the
8e17c34a5cf0 issue2551048. Document WEB_SECRET_KEY in config.ini.
John Rouillard <rouilj@ieee.org>
parents: 5824
diff changeset
53 `upgrading directions`_ using ``roundup-admin ... updateconfig
8e17c34a5cf0 issue2551048. Document WEB_SECRET_KEY in config.ini.
John Rouillard <rouilj@ieee.org>
parents: 5824
diff changeset
54 ...`` will generate the ``secret_key`` comments and setting. Then
8e17c34a5cf0 issue2551048. Document WEB_SECRET_KEY in config.ini.
John Rouillard <rouilj@ieee.org>
parents: 5824
diff changeset
55 you can merge this into your ``config.ini``. If you are
8e17c34a5cf0 issue2551048. Document WEB_SECRET_KEY in config.ini.
John Rouillard <rouilj@ieee.org>
parents: 5824
diff changeset
56 installing a new tracker with ``roundup-admin ... install`` the
8e17c34a5cf0 issue2551048. Document WEB_SECRET_KEY in config.ini.
John Rouillard <rouilj@ieee.org>
parents: 5824
diff changeset
57 ``secret_key`` value is automatically set to some random value.
8e17c34a5cf0 issue2551048. Document WEB_SECRET_KEY in config.ini.
John Rouillard <rouilj@ieee.org>
parents: 5824
diff changeset
58
6205
1b9f6b9befeb Clarify need to set secret_key for rest.
John Rouillard <rouilj@ieee.org>
parents: 6204
diff changeset
59 If ``secret_key`` is not set, the etag value returned by a REST call
1b9f6b9befeb Clarify need to set secret_key for rest.
John Rouillard <rouilj@ieee.org>
parents: 6204
diff changeset
60 will changed on every call even though the item has not changed. This
1b9f6b9befeb Clarify need to set secret_key for rest.
John Rouillard <rouilj@ieee.org>
parents: 6204
diff changeset
61 means users will be unable to submit changes using the rest
1b9f6b9befeb Clarify need to set secret_key for rest.
John Rouillard <rouilj@ieee.org>
parents: 6204
diff changeset
62 interface. (Note, if you run roundup in a persistent mode: server,
1b9f6b9befeb Clarify need to set secret_key for rest.
John Rouillard <rouilj@ieee.org>
parents: 6204
diff changeset
63 wsgi, mod_python, the etag will change on every restart if not
1b9f6b9befeb Clarify need to set secret_key for rest.
John Rouillard <rouilj@ieee.org>
parents: 6204
diff changeset
64 explicitly set.)
5826
8e17c34a5cf0 issue2551048. Document WEB_SECRET_KEY in config.ini.
John Rouillard <rouilj@ieee.org>
parents: 5824
diff changeset
65
8e17c34a5cf0 issue2551048. Document WEB_SECRET_KEY in config.ini.
John Rouillard <rouilj@ieee.org>
parents: 5824
diff changeset
66 .. _upgrading directions: upgrading.html
8e17c34a5cf0 issue2551048. Document WEB_SECRET_KEY in config.ini.
John Rouillard <rouilj@ieee.org>
parents: 5824
diff changeset
67
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
68 Preventing CSRF Attacks
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
69 -----------------------
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
70
8175
bd628e64725f Documentation and fix for REST headers
Ralf Schlatterbeck <rsc@runtux.com>
parents: 8101
diff changeset
71 Clients should set the header ``X-REQUESTED-WITH`` to any value and the
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
72 tracker's config.ini should have ``csrf_enforce_header_x-requested-with
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
73 = yes`` or ``required``.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
74
6681
ab2ed11c021e issue2551205: Add support for specifying valid origins for api: xmlrpc/rest
John Rouillard <rouilj@ieee.org>
parents: 6675
diff changeset
75 If you want to allow Roundup's api to be accessed by an application
ab2ed11c021e issue2551205: Add support for specifying valid origins for api: xmlrpc/rest
John Rouillard <rouilj@ieee.org>
parents: 6675
diff changeset
76 that is not hosted at the same origin as Roundup, you must permit
ab2ed11c021e issue2551205: Add support for specifying valid origins for api: xmlrpc/rest
John Rouillard <rouilj@ieee.org>
parents: 6675
diff changeset
77 the origin using the ``allowed_api_origins`` setting in
ab2ed11c021e issue2551205: Add support for specifying valid origins for api: xmlrpc/rest
John Rouillard <rouilj@ieee.org>
parents: 6675
diff changeset
78 ``config.ini``.
ab2ed11c021e issue2551205: Add support for specifying valid origins for api: xmlrpc/rest
John Rouillard <rouilj@ieee.org>
parents: 6675
diff changeset
79
8175
bd628e64725f Documentation and fix for REST headers
Ralf Schlatterbeck <rsc@runtux.com>
parents: 8101
diff changeset
80 If you access the REST interface with a method other than ``GET``, you
bd628e64725f Documentation and fix for REST headers
Ralf Schlatterbeck <rsc@runtux.com>
parents: 8101
diff changeset
81 must also supply an origin header with a value that is either the
bd628e64725f Documentation and fix for REST headers
Ralf Schlatterbeck <rsc@runtux.com>
parents: 8101
diff changeset
82 default origin (the URL of the tracker without the path component set in
bd628e64725f Documentation and fix for REST headers
Ralf Schlatterbeck <rsc@runtux.com>
parents: 8101
diff changeset
83 the config file as ``web`` in section ``[tracker]``) or one that is
bd628e64725f Documentation and fix for REST headers
Ralf Schlatterbeck <rsc@runtux.com>
parents: 8101
diff changeset
84 permitted by ``allowed_api_origins``.
bd628e64725f Documentation and fix for REST headers
Ralf Schlatterbeck <rsc@runtux.com>
parents: 8101
diff changeset
85
7556
273c8c2b5042 fix(api): - issue2551063 - Rest/Xmlrpc interfaces needs failed login protection.
John Rouillard <rouilj@ieee.org>
parents: 7499
diff changeset
86 Rate Limiting API Failed Logins
273c8c2b5042 fix(api): - issue2551063 - Rest/Xmlrpc interfaces needs failed login protection.
John Rouillard <rouilj@ieee.org>
parents: 7499
diff changeset
87 -------------------------------
273c8c2b5042 fix(api): - issue2551063 - Rest/Xmlrpc interfaces needs failed login protection.
John Rouillard <rouilj@ieee.org>
parents: 7499
diff changeset
88
273c8c2b5042 fix(api): - issue2551063 - Rest/Xmlrpc interfaces needs failed login protection.
John Rouillard <rouilj@ieee.org>
parents: 7499
diff changeset
89 To make brute force password guessing harder, the REST API has an
7600
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
90 invalid login rate limiter. This feature restricts the number of
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
91 failed login attempts made with an invalid user or
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
92 password. Successful login attempts are limited by the normal API rate
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
93 limiter. The rate limiter is a GCRA leaky bucket variant, which is
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
94 shared by all API (REST/XMLRPC) endpoints. However it is important to
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
95 note that the rate limiter for the HTML/web interface is not shared by
7556
273c8c2b5042 fix(api): - issue2551063 - Rest/Xmlrpc interfaces needs failed login protection.
John Rouillard <rouilj@ieee.org>
parents: 7499
diff changeset
96 the API failed login rate limiter.
273c8c2b5042 fix(api): - issue2551063 - Rest/Xmlrpc interfaces needs failed login protection.
John Rouillard <rouilj@ieee.org>
parents: 7499
diff changeset
97
7600
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
98 It is configured through the settings in config.ini. By setting the
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
99 value of ``api_failed_login_limit`` to a non-zero value, the limiter
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
100 is enabled. Setting it to 0 will disables the limiter (although this
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
101 is not recommended). If a user fails to log in more than
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
102 ``api_failed_login_limit`` times in
7556
273c8c2b5042 fix(api): - issue2551063 - Rest/Xmlrpc interfaces needs failed login protection.
John Rouillard <rouilj@ieee.org>
parents: 7499
diff changeset
103 ``api_failed_login_interval_in_sec`` seconds, a 429 HTTP error will be
7600
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
104 returned. The error message also tells the user how long to wait
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
105 before trying to log in again.
7556
273c8c2b5042 fix(api): - issue2551063 - Rest/Xmlrpc interfaces needs failed login protection.
John Rouillard <rouilj@ieee.org>
parents: 7499
diff changeset
106
7600
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
107 When a 429 error is returned, the associated account will be
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
108 temporarily locked until sufficient time has elapsed to generate an
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
109 additional login token. This time period is determined by the values
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
110 of the ``api_failed_login_interval_in_sec`` and ``api_failed_login_limit``
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
111 parameters. Any login attempts made during this lockout period will be
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
112 unsuccessful, even if the correct password is provided. This
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
113 effectively prevents brute force attacks from attempting more than one
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
114 password every
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
115 ``api_failed_login_interval_in_sec/api_failed_login_limit`` seconds on average.
7556
273c8c2b5042 fix(api): - issue2551063 - Rest/Xmlrpc interfaces needs failed login protection.
John Rouillard <rouilj@ieee.org>
parents: 7499
diff changeset
116
7600
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
117 The system's default settings permit a maximum of four login attempts,
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
118 after which the user will experience a delay of 2.5 minutes (150
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
119 seconds). Currently, there is no established procedure for resetting
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
120 the rate limiter.
7556
273c8c2b5042 fix(api): - issue2551063 - Rest/Xmlrpc interfaces needs failed login protection.
John Rouillard <rouilj@ieee.org>
parents: 7499
diff changeset
121
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
122 Rate Limiting the API
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
123 ---------------------
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
124
7600
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
125 Roundup includes Rate Limiting for the API, which is distinct from
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
126 rate limiting login attempts on the web interface.
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
127
7600
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
128 This feature can be enabled by setting the ``api_calls_per_interval``
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
129 and ``api_interval_in_sec`` configuration parameters in the ``[web]``
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
130 section of the ``config.ini`` file. Details for these settings are
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
131 documented in the same file.
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
132
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
133 If ``api_calls_per_interval = 60`` and ``api_interval_in_sec = 60``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
134 the user can make 60 calls in a minute. They can use them all up in the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
135 first second and then get one call back every second. With
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
136 ``api_calls_per_interval = 60`` and ``api_interval_in_sec = 3600`` (1
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
137 hour) they can use all 60 calls in the first second and they get one
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
138 additional call every 10 seconds. ``api_calls_per_interval`` is the
6206
b6f2cf872d2e Expand sunset header explanation, fix formating missing `.
John Rouillard <rouilj@ieee.org>
parents: 6205
diff changeset
139 burst rate that you are willing to allow within ``api_interval_in_sec``
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
140 seconds. The average rate of use is the ratio of
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
141 ``api_calls_per_interval/api_interval_in_sec``. So you can have many
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
142 values that permit one call per second on average: 1/1, 60/60,
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
143 3600/3600, but they all have a different maximum burst rates: 1/sec,
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
144 60/sec and 3600/sec.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
145
7600
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
146 In practice, a single page app may require 20 or 30 API calls to
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
147 populate the page with data, followed by a few seconds of waiting for
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
148 the user to select an issue. When displaying the issue, another 20 or
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
149 more calls may be needed to populate status dropdowns, retrieve the
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
150 first 10 messages in the issue, and so on. Therefore, controlling both
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
151 the burst rate and the average rate is a tuning exercise that is left
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
152 to the tracker admin.
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
153
7600
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
154 It is worth noting that the rate limit feature may be slightly lossy,
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
155 meaning that under heavy load, it may miscount and allow more than the
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
156 burst count. On slower hardware, errors of up to 10% have been
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
157 observed. Using redis, PostgreSQL, or MySQL for storing ephemeral data
5a8a41a2e3c8 docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents: 7582
diff changeset
158 minimizes the loss.
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
159
8100
e97caa8e4dae issue2551315 - Allow admin settable max number of rows to be returned by rest interface.
John Rouillard <rouilj@ieee.org>
parents: 8073
diff changeset
160 Limit Size of Returned Data
e97caa8e4dae issue2551315 - Allow admin settable max number of rows to be returned by rest interface.
John Rouillard <rouilj@ieee.org>
parents: 8073
diff changeset
161 ---------------------------
e97caa8e4dae issue2551315 - Allow admin settable max number of rows to be returned by rest interface.
John Rouillard <rouilj@ieee.org>
parents: 8073
diff changeset
162
e97caa8e4dae issue2551315 - Allow admin settable max number of rows to be returned by rest interface.
John Rouillard <rouilj@ieee.org>
parents: 8073
diff changeset
163 When selecting from the database, you can limit the number of rows
e97caa8e4dae issue2551315 - Allow admin settable max number of rows to be returned by rest interface.
John Rouillard <rouilj@ieee.org>
parents: 8073
diff changeset
164 returned by adding the following to `interfaces.py`_::
e97caa8e4dae issue2551315 - Allow admin settable max number of rows to be returned by rest interface.
John Rouillard <rouilj@ieee.org>
parents: 8073
diff changeset
165
e97caa8e4dae issue2551315 - Allow admin settable max number of rows to be returned by rest interface.
John Rouillard <rouilj@ieee.org>
parents: 8073
diff changeset
166 from roundup.rest import RestfulInstance
e97caa8e4dae issue2551315 - Allow admin settable max number of rows to be returned by rest interface.
John Rouillard <rouilj@ieee.org>
parents: 8073
diff changeset
167 RestfulInstance.max_response_row_size = 26
e97caa8e4dae issue2551315 - Allow admin settable max number of rows to be returned by rest interface.
John Rouillard <rouilj@ieee.org>
parents: 8073
diff changeset
168
e97caa8e4dae issue2551315 - Allow admin settable max number of rows to be returned by rest interface.
John Rouillard <rouilj@ieee.org>
parents: 8073
diff changeset
169 This will limit the setting of ``@page_size`` to 25 (one less than the
e97caa8e4dae issue2551315 - Allow admin settable max number of rows to be returned by rest interface.
John Rouillard <rouilj@ieee.org>
parents: 8073
diff changeset
170 value). If the url includes a ``@page_size`` pagination value greater
e97caa8e4dae issue2551315 - Allow admin settable max number of rows to be returned by rest interface.
John Rouillard <rouilj@ieee.org>
parents: 8073
diff changeset
171 than or equal to the ``max_response_row_size`` you will receive an
e97caa8e4dae issue2551315 - Allow admin settable max number of rows to be returned by rest interface.
John Rouillard <rouilj@ieee.org>
parents: 8073
diff changeset
172 error like::
e97caa8e4dae issue2551315 - Allow admin settable max number of rows to be returned by rest interface.
John Rouillard <rouilj@ieee.org>
parents: 8073
diff changeset
173
e97caa8e4dae issue2551315 - Allow admin settable max number of rows to be returned by rest interface.
John Rouillard <rouilj@ieee.org>
parents: 8073
diff changeset
174 {
e97caa8e4dae issue2551315 - Allow admin settable max number of rows to be returned by rest interface.
John Rouillard <rouilj@ieee.org>
parents: 8073
diff changeset
175 "error": {
e97caa8e4dae issue2551315 - Allow admin settable max number of rows to be returned by rest interface.
John Rouillard <rouilj@ieee.org>
parents: 8073
diff changeset
176 "status": 400,
e97caa8e4dae issue2551315 - Allow admin settable max number of rows to be returned by rest interface.
John Rouillard <rouilj@ieee.org>
parents: 8073
diff changeset
177 "msg": "Page size 30 must be less than admin limit on query
e97caa8e4dae issue2551315 - Allow admin settable max number of rows to be returned by rest interface.
John Rouillard <rouilj@ieee.org>
parents: 8073
diff changeset
178 result size: 26."
e97caa8e4dae issue2551315 - Allow admin settable max number of rows to be returned by rest interface.
John Rouillard <rouilj@ieee.org>
parents: 8073
diff changeset
179 }
e97caa8e4dae issue2551315 - Allow admin settable max number of rows to be returned by rest interface.
John Rouillard <rouilj@ieee.org>
parents: 8073
diff changeset
180 }
e97caa8e4dae issue2551315 - Allow admin settable max number of rows to be returned by rest interface.
John Rouillard <rouilj@ieee.org>
parents: 8073
diff changeset
181
8101
2244205dd7c4 issue2551315 - Allow admin settable max number of rows to be returned by rest interface.
John Rouillard <rouilj@ieee.org>
parents: 8100
diff changeset
182 The default value is 10 million and one rows.
2244205dd7c4 issue2551315 - Allow admin settable max number of rows to be returned by rest interface.
John Rouillard <rouilj@ieee.org>
parents: 8100
diff changeset
183
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
184 Client API
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
185 ==========
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
186
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
187 The top-level REST url ``/rest/`` will display the current version of
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
188 the REST API (Version 1 as of this writing) and some links to relevant
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
189 endpoints of the API. In the following the ``/rest`` prefix is omitted
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
190 from relative REST-API links for brevity.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
191
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
192 Headers
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
193 -------
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
194
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
195 If rate limiting is enabled there are 3 "standard" headers:
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
196
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
197 **X-RateLimit-Limit**: Calls allowed per period.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
198
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
199 **X-RateLimit-Remaining**: Calls available to be completed in this window.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
200
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
201 **X-RateLimit-Reset**: window ends in this many seconds. (Note,
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
202 not an epoch timestamp). After this time, all
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
203 X-RateLimit-Limit calls are available again.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
204
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
205 and one helpful header to report the period that is missing
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
206 from other lists of rate limit headers:
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
207
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
208 **X-RateLimit-Limit-Period**: Defines period in seconds for X-RateLimit-Limit.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
209
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
210 Also if the user has exceeded the rate limit, this header is added:
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
211
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
212 **Retry-After**: The number of second to wait until 1 api call will succeed.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
213
6182
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
214 If the client has requested a deprecated API endpoint, the header:
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
215
6206
b6f2cf872d2e Expand sunset header explanation, fix formating missing `.
John Rouillard <rouilj@ieee.org>
parents: 6205
diff changeset
216 **Sunset**: an http date after which the end point will not be
b6f2cf872d2e Expand sunset header explanation, fix formating missing `.
John Rouillard <rouilj@ieee.org>
parents: 6205
diff changeset
217 available. This is not returned by current code, but can be used
6207
8a21f8ba3065 Doc updates. Mostly formatting.
John Rouillard <rouilj@ieee.org>
parents: 6206
diff changeset
218 when `Programming the REST API`_. It should be used as a hint that
8a21f8ba3065 Doc updates. Mostly formatting.
John Rouillard <rouilj@ieee.org>
parents: 6206
diff changeset
219 the REST endpoint will be going away. See
7139
42e68162279b update links.
John Rouillard <rouilj@ieee.org>
parents: 6774
diff changeset
220 https://www.rfc-editor.org/rfc/rfc8594 for details on this header and
6207
8a21f8ba3065 Doc updates. Mostly formatting.
John Rouillard <rouilj@ieee.org>
parents: 6206
diff changeset
221 the sunset link type.
6182
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
222
6185
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
223 Hyperdb Stats
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
224 -------------
6185
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
225
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
226 Adding ``@stats=true`` as a GET query parameter or POST data item will
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
227 augment the response with an ``@stats`` dictionary. Any value other
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
228 than ``true`` (any case) will disable the ``@stats`` dictionary. When
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
229 stats are enabled the response includes an ``@stats`` member and looks
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
230 like::
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
231
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
232 { "data": {
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
233 ...
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
234 "@stats": {
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
235 "cache_hits": 3,
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
236 "cache_misses": 1,
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
237 "get_items": 0.0009722709655761719,
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
238 "filtering": 0,
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
239 "elapsed": 0.04731464385986328
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
240 }
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
241 }
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
242 }
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
243
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
244 These are the same values returned in the html interface by setting
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
245 the ``CGI_SHOW_TIMING`` environment variable. By default performance
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
246 stats are not shown. The fields are subject to change. An
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
247 understanding of the code is recommended if you are going to use this
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
248 info.
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
249
6182
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
250 Versioning
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
251 ----------
6182
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
252
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
253 Currently there is only one version of the API. Versions are simple
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
254 integers. The current version is ``1``. Version selection is
7636
c5307dc0e8c6 docs: clarify Api version method priority; payload @apiver
John Rouillard <rouilj@ieee.org>
parents: 7600
diff changeset
255 implemented in the server using one of four methods (in priority
c5307dc0e8c6 docs: clarify Api version method priority; payload @apiver
John Rouillard <rouilj@ieee.org>
parents: 7600
diff changeset
256 order, highest first):
6182
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
257
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
258 1. Explicit version param in accept header:
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
259 ``application/json; version=1``
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
260
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
261 2. Version suffix in vendor accept header:
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
262 ``application/vnd.json.test-v1+json``
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
263
7636
c5307dc0e8c6 docs: clarify Api version method priority; payload @apiver
John Rouillard <rouilj@ieee.org>
parents: 7600
diff changeset
264 3. Adding ``@apiver: 1`` in the input data wrapper (for POST, PUT)
c5307dc0e8c6 docs: clarify Api version method priority; payload @apiver
John Rouillard <rouilj@ieee.org>
parents: 7600
diff changeset
265
c5307dc0e8c6 docs: clarify Api version method priority; payload @apiver
John Rouillard <rouilj@ieee.org>
parents: 7600
diff changeset
266 4. Adding version specifier in query string: ``@apiver=1`` (for GET).
c5307dc0e8c6 docs: clarify Api version method priority; payload @apiver
John Rouillard <rouilj@ieee.org>
parents: 7600
diff changeset
267
c5307dc0e8c6 docs: clarify Api version method priority; payload @apiver
John Rouillard <rouilj@ieee.org>
parents: 7600
diff changeset
268 The highest priority version method will be used if multiple
c5307dc0e8c6 docs: clarify Api version method priority; payload @apiver
John Rouillard <rouilj@ieee.org>
parents: 7600
diff changeset
269 methods are used.
6182
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
270
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
271 If an explicit version is not provided, the server default is used.
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
272 The server default is reported by querying the ``/rest/`` endpoint as
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
273 described above.
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
274
6311
be8d5a8e090a Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents: 6288
diff changeset
275 Input Formats
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
276 -------------
6311
be8d5a8e090a Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents: 6288
diff changeset
277
6384
66a061e52435 Test options in rest interface against live server; rest doc update
John Rouillard <rouilj@ieee.org>
parents: 6373
diff changeset
278 For a GET or OPTIONS request, the Content-Type header should
66a061e52435 Test options in rest interface against live server; rest doc update
John Rouillard <rouilj@ieee.org>
parents: 6373
diff changeset
279 not be sent.
66a061e52435 Test options in rest interface against live server; rest doc update
John Rouillard <rouilj@ieee.org>
parents: 6373
diff changeset
280
66a061e52435 Test options in rest interface against live server; rest doc update
John Rouillard <rouilj@ieee.org>
parents: 6373
diff changeset
281 Otherwise Content-Type is allowed to be ``application/json`` or
6311
be8d5a8e090a Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents: 6288
diff changeset
282 ``application/x-www-form-urlencoded``. Any other value returns error
be8d5a8e090a Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents: 6288
diff changeset
283 code 415.
be8d5a8e090a Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents: 6288
diff changeset
284
6674
ff8845ca305e issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents: 6630
diff changeset
285 CORS preflight requests
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
286 ~~~~~~~~~~~~~~~~~~~~~~~
6674
ff8845ca305e issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents: 6630
diff changeset
287
ff8845ca305e issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents: 6630
diff changeset
288 CORS preflight requests are done using the OPTIONS method. They
ff8845ca305e issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents: 6630
diff changeset
289 require that REST be enabled. These requests do not make any changes
ff8845ca305e issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents: 6630
diff changeset
290 or get any information from the database. As a result they are
ff8845ca305e issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents: 6630
diff changeset
291 available to the anonymous user and any authenticated user. The user
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
292 does not need to have ``Rest Access`` permissions. Also these requests
6681
ab2ed11c021e issue2551205: Add support for specifying valid origins for api: xmlrpc/rest
John Rouillard <rouilj@ieee.org>
parents: 6675
diff changeset
293 bypass CSRF checks except for the Origin header check which is always
ab2ed11c021e issue2551205: Add support for specifying valid origins for api: xmlrpc/rest
John Rouillard <rouilj@ieee.org>
parents: 6675
diff changeset
294 run for preflight requests.
6674
ff8845ca305e issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents: 6630
diff changeset
295
6681
ab2ed11c021e issue2551205: Add support for specifying valid origins for api: xmlrpc/rest
John Rouillard <rouilj@ieee.org>
parents: 6675
diff changeset
296 You can permit only allowed ORIGINS by setting ``allowed_api_origins``
ab2ed11c021e issue2551205: Add support for specifying valid origins for api: xmlrpc/rest
John Rouillard <rouilj@ieee.org>
parents: 6675
diff changeset
297 in ``config.ini`` to the list of origins permitted to access your
ab2ed11c021e issue2551205: Add support for specifying valid origins for api: xmlrpc/rest
John Rouillard <rouilj@ieee.org>
parents: 6675
diff changeset
298 api. By default only your tracker's origin is allowed. If a preflight
ab2ed11c021e issue2551205: Add support for specifying valid origins for api: xmlrpc/rest
John Rouillard <rouilj@ieee.org>
parents: 6675
diff changeset
299 request fails, the api request will be stopped by the browser.
ab2ed11c021e issue2551205: Add support for specifying valid origins for api: xmlrpc/rest
John Rouillard <rouilj@ieee.org>
parents: 6675
diff changeset
300
ab2ed11c021e issue2551205: Add support for specifying valid origins for api: xmlrpc/rest
John Rouillard <rouilj@ieee.org>
parents: 6675
diff changeset
301 The following CORS preflight headers are usually added automatically by
ab2ed11c021e issue2551205: Add support for specifying valid origins for api: xmlrpc/rest
John Rouillard <rouilj@ieee.org>
parents: 6675
diff changeset
302 the browser and must all be present:
6674
ff8845ca305e issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents: 6630
diff changeset
303
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
304 * ``Access-Control-Request-Headers``
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
305 * ``Access-Control-Request-Method``
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
306 * ``Origin``
6674
ff8845ca305e issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents: 6630
diff changeset
307
7155
89a59e46b3af improve REST interface security
John Rouillard <rouilj@ieee.org>
parents: 7139
diff changeset
308 The headers of the 204 response depend on the
89a59e46b3af improve REST interface security
John Rouillard <rouilj@ieee.org>
parents: 7139
diff changeset
309 ``allowed_api_origins`` setting. If a ``*`` is included as the
89a59e46b3af improve REST interface security
John Rouillard <rouilj@ieee.org>
parents: 7139
diff changeset
310 first element, any client can read the data but they can not
89a59e46b3af improve REST interface security
John Rouillard <rouilj@ieee.org>
parents: 7139
diff changeset
311 provide authentication. This limits the available data to what
89a59e46b3af improve REST interface security
John Rouillard <rouilj@ieee.org>
parents: 7139
diff changeset
312 the anonymous user can see in the web interface.
89a59e46b3af improve REST interface security
John Rouillard <rouilj@ieee.org>
parents: 7139
diff changeset
313
89a59e46b3af improve REST interface security
John Rouillard <rouilj@ieee.org>
parents: 7139
diff changeset
314 All 204 responses will include the headers:
6674
ff8845ca305e issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents: 6630
diff changeset
315
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
316 * ``Access-Control-Allow-Origin``
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
317 * ``Access-Control-Allow-Headers``
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
318 * ``Access-Control-Allow-Methods``
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
319 * ``Access-Control-Max-Age: 86400``
6674
ff8845ca305e issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents: 6630
diff changeset
320
7155
89a59e46b3af improve REST interface security
John Rouillard <rouilj@ieee.org>
parents: 7139
diff changeset
321 If the client's ORIGIN header matches an entry besides ``*`` in the
89a59e46b3af improve REST interface security
John Rouillard <rouilj@ieee.org>
parents: 7139
diff changeset
322 ``allowed_api_origins`` it will also include:
89a59e46b3af improve REST interface security
John Rouillard <rouilj@ieee.org>
parents: 7139
diff changeset
323
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
324 * ``Access-Control-Allow-Credentials: true``
7155
89a59e46b3af improve REST interface security
John Rouillard <rouilj@ieee.org>
parents: 7139
diff changeset
325
89a59e46b3af improve REST interface security
John Rouillard <rouilj@ieee.org>
parents: 7139
diff changeset
326 permitting the client to log in and perform authenticated operations.
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
327
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
328 If the endpoint accepts the PATCH verb the header ``Accept-Patch`` with
6674
ff8845ca305e issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents: 6630
diff changeset
329 valid mime types (usually `application/x-www-form-urlencoded,
ff8845ca305e issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents: 6630
diff changeset
330 multipart/form-data`) will be included.
ff8845ca305e issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents: 6630
diff changeset
331
ff8845ca305e issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents: 6630
diff changeset
332 It will also include rate limit headers since the request is included
ff8845ca305e issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents: 6630
diff changeset
333 in the rate limit for the URL. The results from the CORS preflight
6675
7542269becfa Fix cache time week -> day.
John Rouillard <rouilj@ieee.org>
parents: 6674
diff changeset
334 should be cached for a day so preflight requests are not expected to
6674
ff8845ca305e issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents: 6630
diff changeset
335 cause a problem. If it is an issue, you can see
ff8845ca305e issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents: 6630
diff changeset
336 `Creating Custom Rate Limits`_
ff8845ca305e issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents: 6630
diff changeset
337 and craft a rate limiter that ignores anonymous OPTIONS requests.
ff8845ca305e issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents: 6630
diff changeset
338
6311
be8d5a8e090a Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents: 6288
diff changeset
339 Response Formats
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
340 ----------------
6311
be8d5a8e090a Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents: 6288
diff changeset
341
be8d5a8e090a Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents: 6288
diff changeset
342 The default response format is json.
be8d5a8e090a Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents: 6288
diff changeset
343
7684
3eca3462ba0c fix: add support for dicttoxml2.py
John Rouillard <rouilj@ieee.org>
parents: 7636
diff changeset
344 If you add the ``dicttoxml2.py`` module you can request XML formatted
6311
be8d5a8e090a Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents: 6288
diff changeset
345 data using the header ``Accept: application/xml`` in your
be8d5a8e090a Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents: 6288
diff changeset
346 request. Both output formats are similar in structure.
be8d5a8e090a Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents: 6288
diff changeset
347
7684
3eca3462ba0c fix: add support for dicttoxml2.py
John Rouillard <rouilj@ieee.org>
parents: 7636
diff changeset
348 ``dicttoxml2.py`` should be installed in the Python install directory,
3eca3462ba0c fix: add support for dicttoxml2.py
John Rouillard <rouilj@ieee.org>
parents: 7636
diff changeset
349 or the file can be added to the Roundup installation directory along
3eca3462ba0c fix: add support for dicttoxml2.py
John Rouillard <rouilj@ieee.org>
parents: 7636
diff changeset
350 side ``rest.py``. It can also be enabled on a per tracker basis by
3eca3462ba0c fix: add support for dicttoxml2.py
John Rouillard <rouilj@ieee.org>
parents: 7636
diff changeset
351 adding ``dicttoxml2.py`` to the lib directory in your tracker home (you
6765
b4bfbd768bc1 How to add dicttoxml at system or tracker level.
John Rouillard <rouilj@ieee.org>
parents: 6764
diff changeset
352 may need to create the directory). Then this can be added to
b4bfbd768bc1 How to add dicttoxml at system or tracker level.
John Rouillard <rouilj@ieee.org>
parents: 6764
diff changeset
353 `interfaces.py`_ to enable xml::
b4bfbd768bc1 How to add dicttoxml at system or tracker level.
John Rouillard <rouilj@ieee.org>
parents: 6764
diff changeset
354
b4bfbd768bc1 How to add dicttoxml at system or tracker level.
John Rouillard <rouilj@ieee.org>
parents: 6764
diff changeset
355 from roundup import rest
b4bfbd768bc1 How to add dicttoxml at system or tracker level.
John Rouillard <rouilj@ieee.org>
parents: 6764
diff changeset
356 from dicttoxml import dicttoxml as dtox # from tracker_root/lib directory
b4bfbd768bc1 How to add dicttoxml at system or tracker level.
John Rouillard <rouilj@ieee.org>
parents: 6764
diff changeset
357
b4bfbd768bc1 How to add dicttoxml at system or tracker level.
John Rouillard <rouilj@ieee.org>
parents: 6764
diff changeset
358 rest.dicttoxml = dtox
b4bfbd768bc1 How to add dicttoxml at system or tracker level.
John Rouillard <rouilj@ieee.org>
parents: 6764
diff changeset
359
8073
57ef20b6c003 docs: fix some missing/broken links.
John Rouillard <rouilj@ieee.org>
parents: 8022
diff changeset
360 .. _interfaces.py: reference.html#interfaces-py-hooking-into-the-core-of-roundup
6765
b4bfbd768bc1 How to add dicttoxml at system or tracker level.
John Rouillard <rouilj@ieee.org>
parents: 6764
diff changeset
361
6311
be8d5a8e090a Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents: 6288
diff changeset
362 The rest interface accepts the http accept header and can include
be8d5a8e090a Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents: 6288
diff changeset
363 ``q`` values to specify the preferred mechanism. This is the preferred
be8d5a8e090a Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents: 6288
diff changeset
364 way to specify alternate acceptable response formats.
be8d5a8e090a Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents: 6288
diff changeset
365
be8d5a8e090a Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents: 6288
diff changeset
366 To make testing from the browser easier, you can also append the
7684
3eca3462ba0c fix: add support for dicttoxml2.py
John Rouillard <rouilj@ieee.org>
parents: 7636
diff changeset
367 extension ``.json`` or ``.xml`` to the path component of the url. This
6311
be8d5a8e090a Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents: 6288
diff changeset
368 will force json or xml (if supported) output. If you use an extension
7685
0e3d31a6b7fd doc: clarify use of .xml or .json extensions in REST interface
John Rouillard <rouilj@ieee.org>
parents: 7684
diff changeset
369 it takes priority over any accept headers. Note the extension does not
0e3d31a6b7fd doc: clarify use of .xml or .json extensions in REST interface
John Rouillard <rouilj@ieee.org>
parents: 7684
diff changeset
370 work for the ``/rest`` or ``/rest/data`` paths. In these cases it
8180
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
371 returns a 404 error. Adding the header ``Accept: application/xml``
7685
0e3d31a6b7fd doc: clarify use of .xml or .json extensions in REST interface
John Rouillard <rouilj@ieee.org>
parents: 7684
diff changeset
372 allows these paths to return xml data.
6311
be8d5a8e090a Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents: 6288
diff changeset
373
be8d5a8e090a Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents: 6288
diff changeset
374 The rest interface returns status 406 if you use an unrecognized
be8d5a8e090a Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents: 6288
diff changeset
375 extension. You will also get a 406 status if none of the entries in
be8d5a8e090a Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents: 6288
diff changeset
376 the accept header are available or if the accept header is invalid.
be8d5a8e090a Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents: 6288
diff changeset
377
8326
5145ad81970a docs: change some last 3.6 references to 3.7 with dropping of 3.6.
John Rouillard <rouilj@ieee.org>
parents: 8228
diff changeset
378 Note: ``dicttoxml2.py`` is an updated version of ``dicttoxml.py`` and
5145ad81970a docs: change some last 3.6 references to 3.7 with dropping of 3.6.
John Rouillard <rouilj@ieee.org>
parents: 8228
diff changeset
379 should be used for Roundup running on Python 3.7 or newer.
7684
3eca3462ba0c fix: add support for dicttoxml2.py
John Rouillard <rouilj@ieee.org>
parents: 7636
diff changeset
380
8180
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
381 Also the ``/binary_content`` attribute endpoint can be used to
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
382 retrieve raw file data in many formats.
6311
be8d5a8e090a Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents: 6288
diff changeset
383
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
384 General Guidelines
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
385 ------------------
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
386
5854
d5aed7106ee6 Need to fix spelling.
John Rouillard <rouilj@ieee.org>
parents: 5843
diff changeset
387 Performing a ``GET`` on an item or property of an item will return an
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
388 ETag header or an @etag property. This needs to be submitted with
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
389 ``DELETE``, ``PUT`` and ``PATCH`` operations on the item using an
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
390 ``If-Match`` header or an ``"@etag`` property in the data payload if
6539
f8df7fed18f6 issue2551175 - Make ETag content-encoding aware.
John Rouillard <rouilj@ieee.org>
parents: 6519
diff changeset
391 the method supports a payload. The ETag header value will include a
f8df7fed18f6 issue2551175 - Make ETag content-encoding aware.
John Rouillard <rouilj@ieee.org>
parents: 6519
diff changeset
392 suffix (starting with '-') indicating the Content-Encoding used to
f8df7fed18f6 issue2551175 - Make ETag content-encoding aware.
John Rouillard <rouilj@ieee.org>
parents: 6519
diff changeset
393 respond to the request. If the response was uncompressed, there will
f8df7fed18f6 issue2551175 - Make ETag content-encoding aware.
John Rouillard <rouilj@ieee.org>
parents: 6519
diff changeset
394 be no suffix. The ``@etag`` property never includes the suffix. Any
f8df7fed18f6 issue2551175 - Make ETag content-encoding aware.
John Rouillard <rouilj@ieee.org>
parents: 6519
diff changeset
395 ETag value suffixed or not can be sent in an ``If-Match`` header as
f8df7fed18f6 issue2551175 - Make ETag content-encoding aware.
John Rouillard <rouilj@ieee.org>
parents: 6519
diff changeset
396 the suffix is ignored during comparison.
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
397
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
398 The exact details of returned data is determined by the value of the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
399 ``@verbose`` query parameter. The various supported values and their
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
400 effects are described in the following sections.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
401
6311
be8d5a8e090a Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents: 6288
diff changeset
402 All output is wrapped in an envelope called ``data``. The output
be8d5a8e090a Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents: 6288
diff changeset
403 format is described in `Response Formats`_ above.
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
404
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
405 When using collection endpoints (think list of issues, users ...), the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
406 ``data`` envelope contains metadata (e.g. total number of items) as
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
407 well as a ``collections`` list of objects::
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
408
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
409 { "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
410 "meta data field1": "value",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
411 "meta data field2": "value",
5854
d5aed7106ee6 Need to fix spelling.
John Rouillard <rouilj@ieee.org>
parents: 5843
diff changeset
412 "collection": [
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
413 { "link": "url to item",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
414 "id": "internal identifier for item" },
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
415 { "link": "url to second item",
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
416 "id": "id item 2" },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
417 ... ]
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
418 "@links": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
419 "relation": [
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
420 { "rel": "relation/subrelation",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
421 "uri": "uri to use to implement relation" },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
422 ...
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
423 ],
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
424 "relation2": [ {...} ], ...
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
425 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
426 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
427 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
428
5854
d5aed7106ee6 Need to fix spelling.
John Rouillard <rouilj@ieee.org>
parents: 5843
diff changeset
429 available meta data is described in the documentation for the
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
430 collections endpoint.
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
431
6207
8a21f8ba3065 Doc updates. Mostly formatting.
John Rouillard <rouilj@ieee.org>
parents: 6206
diff changeset
432 The ``link`` fields implement `HATEOS`_ by supplying a url for the
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
433 resource represented by that object. The "link" parameter with the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
434 value of a url is a special case of the @links parameter.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
435
6207
8a21f8ba3065 Doc updates. Mostly formatting.
John Rouillard <rouilj@ieee.org>
parents: 6206
diff changeset
436 .. _HATEOS: https://en.wikipedia.org/wiki/HATEOAS
8a21f8ba3065 Doc updates. Mostly formatting.
John Rouillard <rouilj@ieee.org>
parents: 6206
diff changeset
437
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
438 In the @links object, each relationship is a list of full link json
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
439 objects. These include rel (relationship) and uri properties. In the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
440 future this may be extended to include other data like content-type.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
441 However including a full @links object for every item includes a lot
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
442 of overhead since in most cases only the self relationship needs to be
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
443 represented.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
444
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
445 Because every object, link and multilink ends up getting a url, the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
446 shorter 'link' representation is used for this special case. The
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
447 ``link`` property expresses the ``self`` relationship and its value is
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
448 the uri property of the full link object. In collections, properties
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
449 from each item can be embedded in the returned data (see ``@fields``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
450 below). This can not be done if the property is called link as that
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
451 conflicts with the self url.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
452
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
453 When using an item endpoint (think an individual issue), metadata is
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
454 included in the ``data`` envelope. Inside of the envelope, the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
455 ``attributes`` object contains the data for the field/properties of
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
456 the issue. Example::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
457
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
458 { "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
459 "meta data field1": "value",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
460 "type": "type of item, issue, user ..."
5854
d5aed7106ee6 Need to fix spelling.
John Rouillard <rouilj@ieee.org>
parents: 5843
diff changeset
461 "link": "link to retrieve item",
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
462 "attributes": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
463 "title": "title of issue",
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
464 "nosy": [
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
465 { "link": "url for user4",
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
466 "id": "4" }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
467 ],
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
468
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
469 ... }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
470 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
471 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
472
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
473 Using a property endpoint (e.g. title or nosy list for an issue) the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
474 ``data`` wrapper has a ``data`` subfield that represents the value of
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
475 the property. This ``data`` subfield may be a simple string (all types
5854
d5aed7106ee6 Need to fix spelling.
John Rouillard <rouilj@ieee.org>
parents: 5843
diff changeset
476 except multilink) or a list of strings (multilink
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
477 properties). Example::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
478
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
479 { "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
480 "type": "description of class",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
481 "@etag": "\"f15e6942f00a41960de45f9413684591\"",
5854
d5aed7106ee6 Need to fix spelling.
John Rouillard <rouilj@ieee.org>
parents: 5843
diff changeset
482 "link": "link to retrieve property",
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
483 "id": "id for object with this property",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
484 "data": "value of property"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
485 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
486 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
487
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
488
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
489 Special Endpoints
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
490 -----------------
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
491
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
492 There are a few special endpoints that provide some additional data.
5854
d5aed7106ee6 Need to fix spelling.
John Rouillard <rouilj@ieee.org>
parents: 5843
diff changeset
493 Tracker administrators can add new endpoints. See
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
494 "Programming the REST API"_ below.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
495
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
496 /summary
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
497 ~~~~~~~~
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
498
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
499 A Summary page can be reached via ``/summary`` via the ``GET`` method.
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
500 This is currently hard-coded for the standard tracker schema shipped
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
501 with roundup and will display a summary of open issues.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
502
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
503 /data
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
504 ~~~~~
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
505
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
506 This is the primary entry point for data from the tracker.
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
507
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
508 The ``/data`` link will display a set of classes of the tracker. All
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
509 classes can be reached via ``/data/<classname>`` where ``<classname>``
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
510 is replace with the name of the class to query, e.g. ``/data/issue``.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
511 Individual items of a class (e.g. a single issue) can be queried by
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
512 giving the issue-id, e.g., ``/data/issue/42``. Individual properties of
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
513 an item can be queried by appending the property, e.g.,
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
514 ``/data/issue/42/title``.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
515
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
516
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
517 All the links mentioned in the following support the http method ``GET``.
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
518 Results of a ``GET`` request will always return the results as a
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
519 dictionary with the entry ``data`` referring to the returned data.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
520
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
521 Details are in the sections below.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
522
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
523 /data/\ *class* Collection
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
524 --------------------------
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
525
7853
03c1b7ae3a68 issue2551328/issue2551264 unneeded next link and total_count incorrect
John Rouillard <rouilj@ieee.org>
parents: 7825
diff changeset
526 When you use the ``GET`` method on a class (like ``/data/issue``), the
03c1b7ae3a68 issue2551328/issue2551264 unneeded next link and total_count incorrect
John Rouillard <rouilj@ieee.org>
parents: 7825
diff changeset
527 ``data`` will include the number of available items in
03c1b7ae3a68 issue2551328/issue2551264 unneeded next link and total_count incorrect
John Rouillard <rouilj@ieee.org>
parents: 7825
diff changeset
528 ``@total_size``. If the size exceeds the administrative limit (which
03c1b7ae3a68 issue2551328/issue2551264 unneeded next link and total_count incorrect
John Rouillard <rouilj@ieee.org>
parents: 7825
diff changeset
529 is 10 million by default), ``@total_size`` will be set to ``-1``. To
03c1b7ae3a68 issue2551328/issue2551264 unneeded next link and total_count incorrect
John Rouillard <rouilj@ieee.org>
parents: 7825
diff changeset
530 navigate to the last page of results, you can use the ``next`` links
03c1b7ae3a68 issue2551328/issue2551264 unneeded next link and total_count incorrect
John Rouillard <rouilj@ieee.org>
parents: 7825
diff changeset
531 or increment ``@page_index`` until the result does not include a
03c1b7ae3a68 issue2551328/issue2551264 unneeded next link and total_count incorrect
John Rouillard <rouilj@ieee.org>
parents: 7825
diff changeset
532 ``next`` ``@link`` or ``@total_size`` is not ``-1``. The value of the
03c1b7ae3a68 issue2551328/issue2551264 unneeded next link and total_count incorrect
John Rouillard <rouilj@ieee.org>
parents: 7825
diff changeset
533 HTTP header ``X-Count-Total`` is the same as ``@total_size``.
03c1b7ae3a68 issue2551328/issue2551264 unneeded next link and total_count incorrect
John Rouillard <rouilj@ieee.org>
parents: 7825
diff changeset
534
03c1b7ae3a68 issue2551328/issue2551264 unneeded next link and total_count incorrect
John Rouillard <rouilj@ieee.org>
parents: 7825
diff changeset
535 A ``collection`` list contains the id and link to the
03c1b7ae3a68 issue2551328/issue2551264 unneeded next link and total_count incorrect
John Rouillard <rouilj@ieee.org>
parents: 7825
diff changeset
536 respective item. For example a get on https://.../rest/data/issue
03c1b7ae3a68 issue2551328/issue2551264 unneeded next link and total_count incorrect
John Rouillard <rouilj@ieee.org>
parents: 7825
diff changeset
537 returns::
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
538
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
539 {
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
540 "data": {
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
541 "collection": [
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
542 {
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
543 "id": "1",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
544 "link": "https://.../rest/data/issue/1"
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
545 },
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
546 {
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
547 "id": "100",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
548 "link": "https://.../rest/data/issue/100"
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
549 }
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
550 ...
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
551 ],
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
552 "@total_size": 171
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
553 }
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
554 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
555
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
556 Collection endpoints support a number of features as seen in the next
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
557 sections.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
558
7853
03c1b7ae3a68 issue2551328/issue2551264 unneeded next link and total_count incorrect
John Rouillard <rouilj@ieee.org>
parents: 7825
diff changeset
559 Having an empty ``collection`` does not mean next next link will not
03c1b7ae3a68 issue2551328/issue2551264 unneeded next link and total_count incorrect
John Rouillard <rouilj@ieee.org>
parents: 7825
diff changeset
560 return more data. The row limit is applied when the query is made to
03c1b7ae3a68 issue2551328/issue2551264 unneeded next link and total_count incorrect
John Rouillard <rouilj@ieee.org>
parents: 7825
diff changeset
561 the database. The result set is then filtered, removing rows that the
03c1b7ae3a68 issue2551328/issue2551264 unneeded next link and total_count incorrect
John Rouillard <rouilj@ieee.org>
parents: 7825
diff changeset
562 user does not have permission to access. So it is possible to have no
03c1b7ae3a68 issue2551328/issue2551264 unneeded next link and total_count incorrect
John Rouillard <rouilj@ieee.org>
parents: 7825
diff changeset
563 data items on a page because the user does not have access to them. If
03c1b7ae3a68 issue2551328/issue2551264 unneeded next link and total_count incorrect
John Rouillard <rouilj@ieee.org>
parents: 7825
diff changeset
564 you use ``@page_size`` near the administrative limit, you may receive
03c1b7ae3a68 issue2551328/issue2551264 unneeded next link and total_count incorrect
John Rouillard <rouilj@ieee.org>
parents: 7825
diff changeset
565 fewer rows than requested. However, this does not mean you are out of
03c1b7ae3a68 issue2551328/issue2551264 unneeded next link and total_count incorrect
John Rouillard <rouilj@ieee.org>
parents: 7825
diff changeset
566 data.
03c1b7ae3a68 issue2551328/issue2551264 unneeded next link and total_count incorrect
John Rouillard <rouilj@ieee.org>
parents: 7825
diff changeset
567
03c1b7ae3a68 issue2551328/issue2551264 unneeded next link and total_count incorrect
John Rouillard <rouilj@ieee.org>
parents: 7825
diff changeset
568 All clients must be programmed to expect pagination decorations in the
03c1b7ae3a68 issue2551328/issue2551264 unneeded next link and total_count incorrect
John Rouillard <rouilj@ieee.org>
parents: 7825
diff changeset
569 response. See the section on pagination below for details.
5982
88316ac61ab0 Add warning about collection size limit as anti-DOS mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5933
diff changeset
570
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
571 Searching
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
572 ~~~~~~~~~
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
573
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
574 Searching is done by adding roundup field names and values as query
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
575 parameters. Using: https://.../rest/data/issue you can search using:
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
576
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
577 .. list-table:: Query Parameters Examples
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
578 :header-rows: 1
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
579 :widths: 20 20 80
7733
835b248bf9fd doc: fix other tables to align cells at top of row.
John Rouillard <rouilj@ieee.org>
parents: 7731
diff changeset
580 :class: valign-top
5677
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
581
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
582 * - Query parameter
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
583 - Field type
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
584 - Explanation
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
585 * - ``title=foo``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
586 - String
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
587 - perform a substring search and find any issue with the word foo
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
588 in the title.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
589 * - ``status=2``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
590 - Link
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
591 - find any issue whose status link is set to the id 2.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
592 * - ``status=open``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
593 - Link
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
594 - find any issue where the name of the status is open.
6764
32f52d14b496 Typo fixes, formatting fixes, jwt -> JWT, add link to JWT issue
John Rouillard <rouilj@ieee.org>
parents: 6681
diff changeset
595 Note this is not a string match so using status=ope will fail.
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
596 * - ``nosy=1``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
597 - MultiLink
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
598 - find any issue where the multilink nosy includes the id 1.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
599 * - ``nosy=admin``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
600 - MultiLink
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
601 - find any issue where the multilink nosy includes the user admin.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
602 Note this is not a string match so using nosy=admi will fail.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
603 * - ``booleanfield=1`` - also values: true, TRUE, yes, YES etc. Other
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
604 values match false.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
605 - Boolean
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
606 - find an issue with the boolean field set to true.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
607
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
608 As seen above, Links and Multilinks can be specified numerically or
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
609 symbolically, e.g., searching for issues in status ``closed`` can be
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
610 achieved by searching for ``status=closed`` or ``status=3`` (provided
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
611 the ``closed`` status has ID 3). Note that even though the symbolic
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
612 name is a string, in this case it is also a key value. As a result it
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
613 only does an exact match.
5677
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
614
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
615 Searching for strings (e.g. the issue title, or a keyword name)
5901
a592e3156134 Added more verbage on "Rest Access" permission and reworked search docs.
John Rouillard <rouilj@ieee.org>
parents: 5898
diff changeset
616 performs a case-insensitive substring search. Searching for
5898
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
617 ``title=Something`` (or in long form title~=Something) will find all
5901
a592e3156134 Added more verbage on "Rest Access" permission and reworked search docs.
John Rouillard <rouilj@ieee.org>
parents: 5898
diff changeset
618 issues with "Something" or "someThing", etc. in the title.
a592e3156134 Added more verbage on "Rest Access" permission and reworked search docs.
John Rouillard <rouilj@ieee.org>
parents: 5898
diff changeset
619
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
620 Changing the search to ``title:=Something`` (note the ``:``) performs an
5901
a592e3156134 Added more verbage on "Rest Access" permission and reworked search docs.
John Rouillard <rouilj@ieee.org>
parents: 5898
diff changeset
621 exact case-sensitive string match for exactly one word ``Something``
a592e3156134 Added more verbage on "Rest Access" permission and reworked search docs.
John Rouillard <rouilj@ieee.org>
parents: 5898
diff changeset
622 with a capital ``S``. Another example is:
5898
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
623 ``title:=test+that+nosy+actually+works.`` where the + signs are spaces
5901
a592e3156134 Added more verbage on "Rest Access" permission and reworked search docs.
John Rouillard <rouilj@ieee.org>
parents: 5898
diff changeset
624 in the string. Replacing ``+`` with the `URL encoding`_ for space
5898
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
625 ``%20`` will also work. Note that you must match the spaces when
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
626 performing exact matches. So ``title:=test++that+nosy+actually+works.``
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
627 matches the word ``test`` with two spaces between ``test`` and
5901
a592e3156134 Added more verbage on "Rest Access" permission and reworked search docs.
John Rouillard <rouilj@ieee.org>
parents: 5898
diff changeset
628 ``that`` in the title.
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
629
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
630 To make this clear, searching
5898
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
631 ``https://.../rest/data/issue?keyword=Foo`` will not work unless there
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
632 is a keyword with a (case sensitive) name field of ``Foo`` which is
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
633 the key field of the keyword. However searching the text property
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
634 ``name`` using ``https://.../rest/data/keyword?name=Foo`` (note
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
635 searching keyword class not issue class) will return matches for
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
636 ``Foo``, ``foobar``, ``foo taz`` etc.
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
637
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
638 In all cases the field ``@total_size`` is reported which is the total
7853
03c1b7ae3a68 issue2551328/issue2551264 unneeded next link and total_count incorrect
John Rouillard <rouilj@ieee.org>
parents: 7825
diff changeset
639 number of items available if you were to retrieve all of them. See
03c1b7ae3a68 issue2551328/issue2551264 unneeded next link and total_count incorrect
John Rouillard <rouilj@ieee.org>
parents: 7825
diff changeset
640 more details in the parent section about ``@total_size`` and when it
03c1b7ae3a68 issue2551328/issue2551264 unneeded next link and total_count incorrect
John Rouillard <rouilj@ieee.org>
parents: 7825
diff changeset
641 can return ``-1``.
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
642
6288
9d132769ed37 Add missing comma to rest.txt.
John Rouillard <rouilj@ieee.org>
parents: 6261
diff changeset
643 Other data types: Date, Interval, Integer, Number need examples and may
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
644 need work to allow range searches. Full text search (e.g. over the
5898
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
645 body of a msg) is a work in progress.
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
646
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
647 .. _URL Encoding: https://en.wikipedia.org/wiki/Percent-encoding
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
648
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
649 Transitive Searching
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
650 ^^^^^^^^^^^^^^^^^^^^
5898
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
651
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
652 In addition to searching an issue by its properties, you can search
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
653 for issues where linked items have a certain property. For example
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
654 using ``/issues?messages.author=1`` will find all issues that include
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
655 (link to) a message created by the admin user. This can also be done
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
656 using: ``/issues?messages.author=admin``. Note that this requires
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
657 search permission for messages.author, user.id, and users.username (to
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
658 perform search with ``admin``. If these search permissions are not
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
659 present, the search will silently drop the attribute.
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
660
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
661 Similarly you can find all issues where the nosy list includes James
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
662 Bond with: ``issue?nosy.realname=james+bond``. The alternate way to
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
663 perform this is to query the user class for the realname:
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
664 ``user?realname=james+bond`` and retrieve the id. Then you can execute
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
665 a second rest call ``issue?nosy=7`` to retrieve issues with id 7.
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
666
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
667 Make sure that search access to the class/properties are granted to the
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
668 user. Note that users can search a field even if they can't view
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
669 it. However they may be able to use searches to discover the value of
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
670 the field even if they can't view it.
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
671
5865
04deafac71ab Implement sorting of collections in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5863
diff changeset
672 Sorting
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
673 ~~~~~~~
5865
04deafac71ab Implement sorting of collections in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5863
diff changeset
674
04deafac71ab Implement sorting of collections in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5863
diff changeset
675 Collection endpoints support sorting. This is controlled by specifying a
04deafac71ab Implement sorting of collections in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5863
diff changeset
676 ``@sort`` parameter with a list of properties of the searched class.
04deafac71ab Implement sorting of collections in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5863
diff changeset
677 Optionally properties can include a sign ('+' or '-') to specify
04deafac71ab Implement sorting of collections in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5863
diff changeset
678 ascending or descending sort, respectively. If no sign is given,
04deafac71ab Implement sorting of collections in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5863
diff changeset
679 ascending sort is selected for this property. The following example
04deafac71ab Implement sorting of collections in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5863
diff changeset
680 would sort by status (in ascending order of the status.order property)
04deafac71ab Implement sorting of collections in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5863
diff changeset
681 and then by id of an issue::
04deafac71ab Implement sorting of collections in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5863
diff changeset
682
04deafac71ab Implement sorting of collections in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5863
diff changeset
683 @sort=status,-id
04deafac71ab Implement sorting of collections in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5863
diff changeset
684
7854
171ff2e487df Add @group for grouping in rest interface.
John Rouillard <rouilj@ieee.org>
parents: 7853
diff changeset
685 Grouping
171ff2e487df Add @group for grouping in rest interface.
John Rouillard <rouilj@ieee.org>
parents: 7853
diff changeset
686 ~~~~~~~~
171ff2e487df Add @group for grouping in rest interface.
John Rouillard <rouilj@ieee.org>
parents: 7853
diff changeset
687
171ff2e487df Add @group for grouping in rest interface.
John Rouillard <rouilj@ieee.org>
parents: 7853
diff changeset
688 Collection endpoints support grouping. This is controlled by
171ff2e487df Add @group for grouping in rest interface.
John Rouillard <rouilj@ieee.org>
parents: 7853
diff changeset
689 specifying a ``@group`` parameter with a list of properties of
171ff2e487df Add @group for grouping in rest interface.
John Rouillard <rouilj@ieee.org>
parents: 7853
diff changeset
690 the searched class. Optionally properties can include a sign
171ff2e487df Add @group for grouping in rest interface.
John Rouillard <rouilj@ieee.org>
parents: 7853
diff changeset
691 ('+' or '-') to specify the groups are sorted in ascending or
171ff2e487df Add @group for grouping in rest interface.
John Rouillard <rouilj@ieee.org>
parents: 7853
diff changeset
692 descending order, respectively. If no sign is given, the groups
171ff2e487df Add @group for grouping in rest interface.
John Rouillard <rouilj@ieee.org>
parents: 7853
diff changeset
693 are returned in ascending order. The following example would
171ff2e487df Add @group for grouping in rest interface.
John Rouillard <rouilj@ieee.org>
parents: 7853
diff changeset
694 return the issues grouped by status (in order from
171ff2e487df Add @group for grouping in rest interface.
John Rouillard <rouilj@ieee.org>
parents: 7853
diff changeset
695 unread->reolved) then within each status, by priority in
171ff2e487df Add @group for grouping in rest interface.
John Rouillard <rouilj@ieee.org>
parents: 7853
diff changeset
696 descending order (wish -> critical)::
171ff2e487df Add @group for grouping in rest interface.
John Rouillard <rouilj@ieee.org>
parents: 7853
diff changeset
697
171ff2e487df Add @group for grouping in rest interface.
John Rouillard <rouilj@ieee.org>
parents: 7853
diff changeset
698 @group=status,-priority
171ff2e487df Add @group for grouping in rest interface.
John Rouillard <rouilj@ieee.org>
parents: 7853
diff changeset
699
171ff2e487df Add @group for grouping in rest interface.
John Rouillard <rouilj@ieee.org>
parents: 7853
diff changeset
700 Adding ``@fields=status,priority`` to the query will allow you to see
171ff2e487df Add @group for grouping in rest interface.
John Rouillard <rouilj@ieee.org>
parents: 7853
diff changeset
701 the status and priority values change so you can identify the items in
171ff2e487df Add @group for grouping in rest interface.
John Rouillard <rouilj@ieee.org>
parents: 7853
diff changeset
702 each group.
171ff2e487df Add @group for grouping in rest interface.
John Rouillard <rouilj@ieee.org>
parents: 7853
diff changeset
703
171ff2e487df Add @group for grouping in rest interface.
John Rouillard <rouilj@ieee.org>
parents: 7853
diff changeset
704 If combined with ``@sort=-id`` within each group he items would be
171ff2e487df Add @group for grouping in rest interface.
John Rouillard <rouilj@ieee.org>
parents: 7853
diff changeset
705 sorted in descending order by id.
171ff2e487df Add @group for grouping in rest interface.
John Rouillard <rouilj@ieee.org>
parents: 7853
diff changeset
706
171ff2e487df Add @group for grouping in rest interface.
John Rouillard <rouilj@ieee.org>
parents: 7853
diff changeset
707 This is useful for select elements that use optgroup.
5865
04deafac71ab Implement sorting of collections in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5863
diff changeset
708
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
709 Pagination
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
710 ~~~~~~~~~~
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
711
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
712 Collection endpoints support pagination. This is controlled by query
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
713 parameters ``@page_size`` and ``@page_index`` (Note the use of the
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
714 leading ``@`` to make the parameters distinguishable from field names.)
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
715
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
716 .. list-table:: Query Parameters Examples
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
717 :header-rows: 1
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
718 :widths: 20 80
7733
835b248bf9fd doc: fix other tables to align cells at top of row.
John Rouillard <rouilj@ieee.org>
parents: 7731
diff changeset
719 :class: valign-top
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
720
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
721 * - Query parameter
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
722 - Explanation
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
723 * - ``@page_size``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
724 - specifies how many items are displayed at once. If no
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
725 ``@page_size`` is specified, all matching items are returned.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
726 * - ``@page_index``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
727 - (which defaults to 1 if not given) specifies which page number
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
728 of ``@page_size`` items is displayed.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
729
5854
d5aed7106ee6 Need to fix spelling.
John Rouillard <rouilj@ieee.org>
parents: 5843
diff changeset
730 Also when pagination is enabled the returned data include pagination
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
731 links along side the collection data. This looks like::
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
732
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
733 { "data":
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
734 {
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
735 "collection": { ... },
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
736 "@total_size": 222,
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
737 "@links": {
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
738 "self": [
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
739 {
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
740 "uri":
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
741 "https://.../rest/data/issue?@page_index=1&@fields=status&@page_size=5",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
742 "rel": "self"
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
743 }
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
744 ],
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
745 "next": [
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
746 {
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
747 "uri":
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
748 "https://.../rest/data/issue?@page_index=2&@fields=status&@page_size=5",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
749 "rel": "next"
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
750 }
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
751 ]
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
752 }
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
753 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
754 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
755
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
756 The ``@links`` parameter is a dictionary indexed by
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
757 relationships. Each relationship is a list of one or more full link
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
758 json objects. Above we have link relations to move to the next
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
759 page. If we weren't at the first page, there would be a ``prev``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
760 relation to move to the previous page. Also we have a self relation
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
761 (which is missing the @page_index, hence we are at page 1) that can be
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
762 used to get the same page again.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
763
5982
88316ac61ab0 Add warning about collection size limit as anti-DOS mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5933
diff changeset
764 Note that the server may choose to limit the number of returned
88316ac61ab0 Add warning about collection size limit as anti-DOS mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5933
diff changeset
765 entries in the collection as a DOS prevention measure. As a result
88316ac61ab0 Add warning about collection size limit as anti-DOS mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5933
diff changeset
766 clients must be prepared to handle the incomplete response and request
88316ac61ab0 Add warning about collection size limit as anti-DOS mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5933
diff changeset
767 the next URL to retrieve all of the entries.
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
768
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
769 Field embedding and verbose output
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
770 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
771
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
772 In collections, you can specify what fields should be embedded in the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
773 returned data. There are some shortcuts provided using the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
774 ``@verbose`` parameter. All the examples in this section are for a GET
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
775 operation on ``https://.../rest/data/issue``.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
776
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
777 .. list-table:: Query Parameters Examples
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
778 :header-rows: 1
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
779 :widths: 20 80
7731
4c85e3e16dfe doc: fix link; make cells in table align at top
John Rouillard <rouilj@ieee.org>
parents: 7685
diff changeset
780 :class: valign-top
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
781
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
782 * - Query parameter
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
783 - Explanation
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
784 * - ``@verbose=0``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
785 - each item in the collection has its "id" property displayed
5854
d5aed7106ee6 Need to fix spelling.
John Rouillard <rouilj@ieee.org>
parents: 5843
diff changeset
786 and a link with the URL to retrieve the item.
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
787 * - ``@verbose=1``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
788 - for collections this output is the same as ``@verbose=0``. This
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
789 is the default.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
790 * - ``@verbose=2``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
791 - each item in the collection includes the "label" property in
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
792 addition to "id" property and a link for the item.
7731
4c85e3e16dfe doc: fix link; make cells in table align at top
John Rouillard <rouilj@ieee.org>
parents: 7685
diff changeset
793 This is useful as documented below in `Searches and selection`_.
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
794 * - ``@verbose=3``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
795 - will display the content property of messages and files. Note
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
796 warnings about this below. Using this for collections is
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
797 discouraged as it is slow and produces a lot of data.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
798 * - ``@fields=status,title``
5824
352e78c3b4ab Allow @fields to include protected properties, document @protected
John Rouillard <rouilj@ieee.org>
parents: 5738
diff changeset
799 - will return the ``status`` and ``title`` fields for the
352e78c3b4ab Allow @fields to include protected properties, document @protected
John Rouillard <rouilj@ieee.org>
parents: 5738
diff changeset
800 displayed issues. It is added to the fields returned by the
352e78c3b4ab Allow @fields to include protected properties, document @protected
John Rouillard <rouilj@ieee.org>
parents: 5738
diff changeset
801 @verbose parameter. Protected properties
352e78c3b4ab Allow @fields to include protected properties, document @protected
John Rouillard <rouilj@ieee.org>
parents: 5738
diff changeset
802 can be included in the list and will be returned.
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
803
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
804 In addition collections support the ``@fields`` parameter which is a
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
805 colon or comma separated list of fields to embed in the response. For
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
806 example ``https://.../rest/data/issue?@verbose=2`` is the same as:
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
807 ``https://.../rest/data/issue?@fields=title`` since the label property
6090
e097ff5064b8 Allow transitive properties in @fields in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5982
diff changeset
808 for an issue is its title.
e097ff5064b8 Allow transitive properties in @fields in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5982
diff changeset
809 The @fields option supports transitive properties, e.g.
e097ff5064b8 Allow transitive properties in @fields in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5982
diff changeset
810 ``status.name``. The transitive property may not include multilinks in
e097ff5064b8 Allow transitive properties in @fields in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5982
diff changeset
811 the path except for the last component. So ``messages.author`` is not
e097ff5064b8 Allow transitive properties in @fields in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5982
diff changeset
812 allowed because ``messages`` is a multilink while ``messages`` alone
e097ff5064b8 Allow transitive properties in @fields in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5982
diff changeset
813 would be allowed. You can use both ``@verbose`` and
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
814 ``@fields`` to get additional info. For example
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
815 ``https://.../rest/data/issue?@verbose=2&@fields=status`` returns::
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
816
6090
e097ff5064b8 Allow transitive properties in @fields in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5982
diff changeset
817
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
818 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
819 "data": {
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
820 "collection": [
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
821 {
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
822 "link": "https://.../rest/data/issue/1",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
823 "title": "Welcome to the tracker START HERE",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
824 "id": "1",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
825 "status": {
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
826 "link": "https://.../rest/data/status/1",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
827 "id": "1",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
828 "name": "new"
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
829 }
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
830 },
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
831 ...
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
832 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
833
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
834 the format of the status field (included because of
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
835 ``@fields=status``) includes the label for the status. This is due to
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
836 inclusion of ``@verbose=2``. Without verbose you would see::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
837
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
838 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
839 "data": {
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
840 "collection": [
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
841 {
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
842 "link": "https://.../rest/data/issue/1",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
843 "id": "1",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
844 "status": {
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
845 "link": "https://.../rest/data/status/1",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
846 "id": "1"
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
847 }
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
848 },
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
849 ...
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
850 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
851
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
852 Note that the ``link`` field that is returned doesn't exist in the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
853 database. It is a construct of the rest interface. This means that you
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
854 can not set ``@fields=link`` and get the link property included in the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
855 output.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
856
5854
d5aed7106ee6 Need to fix spelling.
John Rouillard <rouilj@ieee.org>
parents: 5843
diff changeset
857 Also using ``@fields=@etag`` will not work to retrieve the etag for
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
858 items in the collection.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
859
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
860 See the `Searches and selection`_ section for the use cases supported
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
861 by these features.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
862
5928
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
863 Getting Message and Files Content
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
864 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5928
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
865
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
866 You can retreive a message with a url like
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
867 ``https://.../demo/rest/data/msg/11``. This returns something like::
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
868
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
869 {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
870 "data": {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
871 "id": "11",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
872 "type": "msg",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
873 "link": "https://.../demo/rest/data/msg/11",
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
874 "attributes": {
5928
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
875 "author": {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
876 "id": "5",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
877 "link": "https://.../demo/rest/data/user/5"
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
878 },
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
879 "content": {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
880 "link": "https://.../demo/msg11/"
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
881 },
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
882 "date": "2017-10-30.00:53:15",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
883 "files": [],
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
884 "inreplyto": null,
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
885 "messageid": "<1509324807.14.0.296813919751.issue3@localhost>",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
886 "messagetype": {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
887 "id": "1",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
888 "link": "https://.../demo/rest/data/msgtype/1"
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
889 },
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
890 "recipients": [
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
891 {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
892 "id": "1",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
893 "link": "https://.../demo/rest/data/user/1"
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
894 },
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
895 {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
896 "id": "3",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
897 "link": "https://.../demo/rest/data/user/3"
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
898 },
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
899 {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
900 "id": "4",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
901 "link": "https://.../demo/rest/data/user/4"
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
902 }
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
903 ],
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
904 "subject": null,
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
905 "summary": "of has to who. or of account give because the",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
906 },
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
907 "@etag": "\"584f82231079e349031bbb853747df1c\""
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
908 }
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
909 }
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
910
8180
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
911 With Roundup 2.5 you can retrieve the data directly from the rest
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
912 interface using the ``Accept`` header value to select a structured (json
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
913 or optional xml) representation (as above) or a stream with just the
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
914 content data.
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
915
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
916 Using the wildcard type ``*/*`` in the ``Accept`` header with the url
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
917 ``.../binary_content`` will return the raw data and the recorded mime
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
918 type of the the data as the ``Content-Type``. Using ``*/*`` with
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
919 another end point will return ``json`` data. An ``Accept`` value of
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
920 ``application/octet-stream`` matches any mime type and retrieves the
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
921 raw data as ``Content-Type: application/octet-stream``.
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
922
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
923 To access the contents of a PNG image file (in file23), you use the
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
924 following link:
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
925 ``https://.../demo/rest/data/file/23/binary_content``. To find out the
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
926 mime type, you can check this URL:
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
927 ``https://.../demo/rest/data/file/23/type``.
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
928
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
929 By setting the header to ``Accept: application/octet-stream; q=1.0,
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
930 application/json; q=0.5``, you will receive the binary PNG file with
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
931 the header ``Content-Type: application/octet-stream``. If you switch
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
932 the ``q`` values, you will receive the encoded JSON version::
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
933
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
934 {
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
935 "data": {
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
936 "id": "23",
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
937 "type": "<class 'bytes'>",
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
938 "link": "https://.../demo/rest/data/file/23/binary_content",
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
939 "data": "b'\\x89PNG\\r\\n\\x1a\\n\\x00[...]0\\x00\\x00\\x00IEND\\xaeB`\\x82'",
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
940 "@etag": "\"db6adc1b09d95b0388d79c7905bc7982\""
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
941 }
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
942 }
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
943
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
944 with ``Content-Type: application/json`` and a (4x larger) json encoded
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
945 representation of the binary data.
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
946
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
947 If you want it returned with a ``Content-Type: image/png`` header,
8543
1ffa1f42e1da refactor: rework mime type comparison and clean code
John Rouillard <rouilj@ieee.org>
parents: 8391
diff changeset
948 you can use ``image/png``, ``image/*``, or ``*/*`` in the Accept header.
8180
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
949
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
950 For message files, you can use
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
951 ``https://.../demo/rest/data/msg/23/binary_content`` with ``Accept:
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
952 application/octet-stream; q=0.5, application/json; q=0.4, image/png;
8543
1ffa1f42e1da refactor: rework mime type comparison and clean code
John Rouillard <rouilj@ieee.org>
parents: 8391
diff changeset
953 q=0.495, text/*``. It will return the plain text (text/plain mime
1ffa1f42e1da refactor: rework mime type comparison and clean code
John Rouillard <rouilj@ieee.org>
parents: 8391
diff changeset
954 type) of the message.
8180
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
955
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
956 Most message files are not stored with a mime type. Getting
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
957 ``https://.../demo/rest/data/msg/23/type`` returns::
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
958
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
959 {
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
960 "data": {
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
961 "id": "23",
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
962 "type": "<class 'NoneType'>",
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
963 "link": "https://.../demo/rest/data/msg/23/type",
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
964 "data": null,
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
965 "@etag": "\"ba98927a8bb4c56f6cfc31a36f94ad16\""
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
966 }
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
967 }
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
968
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
969 The data attribute will usually be null/empty. As a result, mime type
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
970 matching for an item without a mime type is forgiving.
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
971
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
972 Messages are meant to be human readable, so the mime type ``text/*``
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
973 can be used to access any text style mime type (``text/plain``,
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
974 ``text/x-rst``, ``text/markdown``, ``text/html``, ...) or an empty
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
975 mime type. If the item's type is not empty, it will be used as the
8543
1ffa1f42e1da refactor: rework mime type comparison and clean code
John Rouillard <rouilj@ieee.org>
parents: 8391
diff changeset
976 Content-Type (similar to ``*/*``). Otherwise the default mime type
1ffa1f42e1da refactor: rework mime type comparison and clean code
John Rouillard <rouilj@ieee.org>
parents: 8391
diff changeset
977 ``text/plain`` will be the Content-Type. The default mime type can be
1ffa1f42e1da refactor: rework mime type comparison and clean code
John Rouillard <rouilj@ieee.org>
parents: 8391
diff changeset
978 changed using ``interfaces.py`` in your tracker. So you can change the
1ffa1f42e1da refactor: rework mime type comparison and clean code
John Rouillard <rouilj@ieee.org>
parents: 8391
diff changeset
979 default ``text/plain`` to ``text/markdown`` using::
1ffa1f42e1da refactor: rework mime type comparison and clean code
John Rouillard <rouilj@ieee.org>
parents: 8391
diff changeset
980
1ffa1f42e1da refactor: rework mime type comparison and clean code
John Rouillard <rouilj@ieee.org>
parents: 8391
diff changeset
981 from roundup.rest import RestfulInstance
1ffa1f42e1da refactor: rework mime type comparison and clean code
John Rouillard <rouilj@ieee.org>
parents: 8391
diff changeset
982 RestfulInstance.default_text_file_mimetype = "text/markdown"
1ffa1f42e1da refactor: rework mime type comparison and clean code
John Rouillard <rouilj@ieee.org>
parents: 8391
diff changeset
983
1ffa1f42e1da refactor: rework mime type comparison and clean code
John Rouillard <rouilj@ieee.org>
parents: 8391
diff changeset
984 If your tracker supports markup languages (e.g. markdown), you should
1ffa1f42e1da refactor: rework mime type comparison and clean code
John Rouillard <rouilj@ieee.org>
parents: 8391
diff changeset
985 set the mime type (e.g. ``text/markdown``) when storing your message.
8180
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
986
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
987 Note that the header ``X-Content-Type-Options: nosniff`` is returned
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
988 with a non javascript or xml binary_content response to prevent the
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
989 browser from trying to interpret the returned data.
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
990
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
991 Legacy Method (HTML interface)
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
992 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
993
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
994 With the addition of file binary content streaming in the rest
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
995 interface to Roundup 2.5.0, this method (using the html interface) is
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
996 considered legacy but still works.
d02ce1d14acd feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents: 8175
diff changeset
997
5928
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
998 To retreive the content, you can use the content link property:
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
999 ``https://.../demo/msg11/``. The trailing / is required. Without the
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1000 /, you get a web page that includes metadata about the message. With
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1001 the slash you get a text/plain (in most cases) data stream.
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1002
6630
0351caa802f7 Add missing url in example.
John Rouillard <rouilj@ieee.org>
parents: 6586
diff changeset
1003 Also you can use the url: ``https://.../demo/rest/data/msg/11?@verbose=3``
5928
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1004 and the content property (if the data is utf-8 compatible) now looks
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1005 like::
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1006
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1007 ...
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1008 "author": {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1009 "id": "5",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1010 "link": "https://.../demo/rest/data/user/5"
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1011 },
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1012 "content": "of has to who pleasure. or of account give because the
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1013 reprehenderit\neu to quisquam velit, passage,
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1014 was or toil BC quis denouncing quia\nexercise,
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1015 veritatis et used voluptas I elit, a The...",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1016 "date": "2017-10-30.00:53:15",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1017 ...
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1018
5928
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1019 Lines are wrapped for display, content value is one really long
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1020 line. If the data is not utf-8 compatible, you will get a link.
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1021
5929
0368d75de544 issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents: 5928
diff changeset
1022 Retrieving the contents of a file is similar. Performing a
0368d75de544 issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents: 5928
diff changeset
1023 get on ``https://.../demo/rest/data/file/11`` returns::
5928
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1024
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1025 {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1026 "data": {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1027 "id": "11",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1028 "type": "file",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1029 "link": "https://.../demo/rest/data/file/11",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1030 "attributes": {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1031 "acl": null,
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1032 "content": {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1033 "link": "https://.../demo/file11/"
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1034 },
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1035 "name": "afile",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1036 "status": {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1037 "id": "1",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1038 "link": "https://.../demo/rest/data/filestatus/1"
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1039 },
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1040 "type": "image/vnd.microsoft.icon"
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1041 },
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1042 "@etag": "\"74276f75ef71a30a0cce62dc6a8aa1bb\""
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1043 }
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1044 }
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1045
5929
0368d75de544 issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents: 5928
diff changeset
1046 To download the file contents for this example you would
0368d75de544 issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents: 5928
diff changeset
1047 perform an http GET using: ``https://.../demo/file11/``. The trailing
0368d75de544 issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents: 5928
diff changeset
1048 / is required. You will receive a response of type
5928
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1049 application/octet-stream.
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1050
5929
0368d75de544 issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents: 5928
diff changeset
1051 If you perform a get on
0368d75de544 issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents: 5928
diff changeset
1052 ``https://.../demo/rest/data/file/11?@verbose=3`` the content field
0368d75de544 issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents: 5928
diff changeset
1053 above is displayed as (wrapped for display)::
5928
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1054
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1055 "content": "file11 is not text, retrieve using binary_content
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1056 property. mdsum: bd990c0f8833dd991daf610b81b62316",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1057
5929
0368d75de544 issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents: 5928
diff changeset
1058 You can use the `binary_content property`_ described below to
5928
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1059 retrieve an encoded copy of the data.
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1060
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1061 Other query params
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
1062 ~~~~~~~~~~~~~~~~~~
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1063
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1064 This table lists other supported parameters:
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1065
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1066 .. list-table:: Query Parameters Examples
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1067 :header-rows: 1
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1068 :widths: 20 80
7733
835b248bf9fd doc: fix other tables to align cells at top of row.
John Rouillard <rouilj@ieee.org>
parents: 7731
diff changeset
1069 :class: valign-top
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1070
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1071 * - Query parameter
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1072 - Explanation
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1073 * - ``@pretty=false``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1074 - by default json data is pretty printed to make it readable to
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1075 humans. This eases testing and with compression enabled the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1076 extra whitespace doesn't bloat the returned payload excessively.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1077 You can disable pretty printing by using this query parameter.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1078 Note the default is true, so @pretty=true is not supported at
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1079 this time.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1080
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1081 Using the POST method
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
1082 ~~~~~~~~~~~~~~~~~~~~~
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
1083
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
1084 Only class links support the ``POST`` method for creation of new items
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
1085 of a class, e.g., a new issue via the ``/data/issue`` link. The post
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
1086 gets a dictionary of keys/values for the new item. It returns the same
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
1087 parameters as the GET method after successful creation.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
1088
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1089 If you perform a get on an item with ``@verbose=0``, it is in the
8212
79b9343794f5 doc: fix typo.
John Rouillard <rouilj@ieee.org>
parents: 8180
diff changeset
1090 correct form to use as the payload of a post.
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
1091
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
1092
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1093 Safely Re-sending POST
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1094 ^^^^^^^^^^^^^^^^^^^^^^
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1095
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1096 POST is used to create new object in a class. E.G. a new issue. One
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1097 problem is that a POST may time out. Because it is not idempotent like
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1098 a PUT or DELETE, retrying the interrupted POST may result in the
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1099 creation of a duplicate issue.
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
1100
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1101 To solve this problem, a two step process inspired by the POE - Post
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1102 Once Exactly spec:
7139
42e68162279b update links.
John Rouillard <rouilj@ieee.org>
parents: 6774
diff changeset
1103 https://datatracker.ietf.org/doc/html/draft-nottingham-http-poe-00 is provided.
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
1104
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1105 This mechanism returns a single use URL. POSTing to the URL creates
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1106 a new object in the class.
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
1107
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1108 First we get the URL. Here is an example using curl::
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
1109
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1110 curl -u demo:demo -s -X POST -H "Referer: https://.../demo/" \
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1111 -H "X-requested-with: rest" \
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1112 -H "Content-Type: application/json" \
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1113 --data '' \
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1114 https://.../demo/rest/data/issue/@poe
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
1115
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1116 This will return a json payload like::
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
1117
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1118 {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1119 "data": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1120 "expires": 1555266310.4457426,
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1121 "link": "https://.../demo/rest/data/issue/@poe/vizl713xHtIzANRW9jPb3bWXePRzmehdmSXzEta1"
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1122 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1123 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1124
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1125 The value of expires is a Unix timestamp in seconds. In this case it
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1126 has the default lifetime of 30 minutes after the current time. Using
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1127 the link more than 30 minutes into the future will cause a 400 error.
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
1128
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1129 Within 30 minutes, the link can be used to post an issue with the same
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1130 payload that would normally be sent to:
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1131 ``https://.../demo/rest/data/issue``.
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1132
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1133 For example::
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
1134
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1135 curl -u demo:demo -s -X POST \
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1136 -H "Referer: https://.../demo/" \
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1137 -H "X-requested-with: rest" \
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1138 -H "Content-Type: application/json" \
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1139 --data-binary '{ "title": "a problem" }' \
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1140 https://.../demo/rest/data/issue/@poe/vizl713xHtIzANRW9jPb3bWXePRzmehdmSXzEta1
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1141
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1142 returns::
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
1143
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1144 {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1145 "data": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1146 "link": "https://.../demo/rest/data/issue/2280",
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1147 "id": "2280"
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1148 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1149 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1150
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1151 Once the @poe link is used and creates an issue, it becomes invalid
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1152 and can't be used again. Posting to it after the issue, or other
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1153 object, is created, results in a 400 error [#poe_retry]_.
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
1154
6261
424f70c076b9 Grammar fix. Remove word missed in rewrite.
John Rouillard <rouilj@ieee.org>
parents: 6207
diff changeset
1155 Note that POE links are restricted to the class that was used to
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1156 get the link. So you can only create an issue using the link returned
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1157 from ``rest/data/issue/@poe``. You can create a generic POE link by adding
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1158 the "generic" field to the post payload::
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
1159
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1160 curl -u demo:demo -s -X POST -H "Referer: https://.../demo/" \
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1161 -H "X-requested-with: rest" \
6194
0f0dedd2f95d Fix example to have 15 minute lifetime to match text.
John Rouillard <rouilj@ieee.org>
parents: 6185
diff changeset
1162 --data 'lifetime=900&generic=1' \
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1163 https://.../demo/rest/data/issue/@poe
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
1164
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1165 This will return a link under: ``https://.../demo/rest/data/issue/@poe``::
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
1166
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1167 {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1168 "data": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1169 "expires": 1555268640.9606116,
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1170 "link":
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1171 "https://.../demo/rest/data/issue/@poe/slPrzmEq6Q9BTjvcKhfxMNZL4uHXjbHCidY1ludZ"
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
1172 }
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1173 }
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
1174
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1175 You could use the link and change 'issue' to 'user' and it would work
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1176 to create a user. Creating generic POE tokens is *not* recommended,
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1177 but is available if a use case requires it.
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1178
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1179 This example also changes the lifetime of the POE url. This link has
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1180 a lifetime of 15 minutes (900 seconds). Using it after 16 minutes will
8228
11ebd3a19c9a doc: explicitly refer to POE lifetime in seconds.
John Rouillard <rouilj@ieee.org>
parents: 8218
diff changeset
1181 result in a 400 error. A lifetime up to 3600 seconds (1 hour) can be
11ebd3a19c9a doc: explicitly refer to POE lifetime in seconds.
John Rouillard <rouilj@ieee.org>
parents: 8218
diff changeset
1182 specified.
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1183
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1184 POE url's are an optional mechanism. If:
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
1185
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1186 * you do not expect your client to retry a failed post,
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1187 * a failed post is unlikely (e.g. you are running over a local lan),
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1188 * there is a human using the client and who can intervene if a post
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1189 fails
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1190
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1191 you can use the url ``https://.../demo/data/<class>``. However if you
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1192 are using this mechanism to automate creation of objects and will
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1193 automatically retry a post until it succeeds, please use the POE
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1194 mechanism.
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1195
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1196 .. [#poe_retry] As a future enhancement, performing a POST to the POE
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1197 link soon after it has been used to create an object will
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1198 change. It will not return a 400 error. It will will trigger a
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1199 301 redirect to the url for the created object. After some
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1200 period of time (maybe a week) the POE link will be removed and
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1201 return a 400 error. This is meant to allow the client (a time
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1202 limited way) to retrieve the created resource if the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1203 response was lost.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1204
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1205 Other Supported Methods for Collections
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
1206 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1207
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1208 Supports the ``OPTIONS`` method for determining which methods are
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1209 allowed on a given endpoint.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1210
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1211 Does not support PUT, DELETE or PATCH.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1212
7972
425dd9854e34 feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents: 7878
diff changeset
1213 /data/user/roles endpoint
425dd9854e34 feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents: 7878
diff changeset
1214 -------------------------
425dd9854e34 feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents: 7878
diff changeset
1215
425dd9854e34 feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents: 7878
diff changeset
1216 The list of valid roles for a user is not an actual class in the
425dd9854e34 feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents: 7878
diff changeset
1217 hyperdb. This endpoint returns a list of all defined roles if the
425dd9854e34 feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents: 7878
diff changeset
1218 user has the ``Admin`` role. Otherwise it returns a 403 - not
425dd9854e34 feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents: 7878
diff changeset
1219 authorized error. The output from this endpoint looks like::
425dd9854e34 feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents: 7878
diff changeset
1220
425dd9854e34 feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents: 7878
diff changeset
1221 {
425dd9854e34 feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents: 7878
diff changeset
1222 "data": {
425dd9854e34 feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents: 7878
diff changeset
1223 "collection": [
425dd9854e34 feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents: 7878
diff changeset
1224 {
425dd9854e34 feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents: 7878
diff changeset
1225 "id": "user",
425dd9854e34 feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents: 7878
diff changeset
1226 "name": "user"
425dd9854e34 feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents: 7878
diff changeset
1227 },
425dd9854e34 feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents: 7878
diff changeset
1228 {
425dd9854e34 feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents: 7878
diff changeset
1229 "id": "admin",
425dd9854e34 feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents: 7878
diff changeset
1230 "name": "admin"
425dd9854e34 feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents: 7878
diff changeset
1231 },
425dd9854e34 feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents: 7878
diff changeset
1232 {
425dd9854e34 feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents: 7878
diff changeset
1233 "id": "anonymous",
425dd9854e34 feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents: 7878
diff changeset
1234 "name": "anonymous"
425dd9854e34 feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents: 7878
diff changeset
1235 }
425dd9854e34 feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents: 7878
diff changeset
1236 ]
425dd9854e34 feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents: 7878
diff changeset
1237 }
425dd9854e34 feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents: 7878
diff changeset
1238 }
425dd9854e34 feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents: 7878
diff changeset
1239
425dd9854e34 feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents: 7878
diff changeset
1240 to mimic a class collection.
425dd9854e34 feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents: 7878
diff changeset
1241
425dd9854e34 feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents: 7878
diff changeset
1242 Unlike a real class collection endpoint, ``@total_size`` is not
7973
ab3506b9e315 doc: add /rest/data/user/roles ignores query options
John Rouillard <rouilj@ieee.org>
parents: 7972
diff changeset
1243 returned. Also it does not support and ignores any query options like:
7980
372517700dad docs: fix formatting.
John Rouillard <rouilj@ieee.org>
parents: 7973
diff changeset
1244 filtering, ``@sort``, ``@group``, ``@verbose`` etc. Note that the ``id``
7973
ab3506b9e315 doc: add /rest/data/user/roles ignores query options
John Rouillard <rouilj@ieee.org>
parents: 7972
diff changeset
1245 property is not numeric.
7972
425dd9854e34 feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents: 7878
diff changeset
1246
425dd9854e34 feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents: 7878
diff changeset
1247 This endpoint was introduced in release 2.4.0 to support a roles
425dd9854e34 feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents: 7878
diff changeset
1248 select/dropdown in the web component classhelper. This lets the web
425dd9854e34 feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents: 7878
diff changeset
1249 component helper implement the same function in the classic user class
425dd9854e34 feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents: 7878
diff changeset
1250 classhelper.
425dd9854e34 feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents: 7878
diff changeset
1251
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1252 /data/\ *class*/\ *id* item
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
1253 ---------------------------
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1254
7853
03c1b7ae3a68 issue2551328/issue2551264 unneeded next link and total_count incorrect
John Rouillard <rouilj@ieee.org>
parents: 7825
diff changeset
1255 When you use the ``GET`` method on an item
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1256 (e.g. ``/data/issue/42``), a ``link`` attribute contains the link to
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1257 the item, ``id`` contains the id, ``type`` contains the class name
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1258 (e.g. ``issue`` in the example) and an ``etag`` property can be used
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1259 to detect modifications since the last query.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1260
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1261 Individual properties of the item are returned in an ``attributes``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1262 dictionary. The properties returned depend on the permissions of the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1263 account used for the query.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1264
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1265 By default all (visible to the current user) attributes/properties are
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1266 returned. You can limit this by using the ``@fields`` query parameter
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1267 similar to how it is used in collections. This way you can only return
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1268 the fields you are interested in reducing network load as well as
6090
e097ff5064b8 Allow transitive properties in @fields in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5982
diff changeset
1269 memory and parsing time on the client side. Or you can add additional
e097ff5064b8 Allow transitive properties in @fields in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5982
diff changeset
1270 transitive properties. By default protected
5892
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
1271 properties (read only in the database) are not listed. This
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
1272 makes it easier to submit the attributes from a
5824
352e78c3b4ab Allow @fields to include protected properties, document @protected
John Rouillard <rouilj@ieee.org>
parents: 5738
diff changeset
1273 ``@verbose=0`` query using PUT. To include protected properties
5854
d5aed7106ee6 Need to fix spelling.
John Rouillard <rouilj@ieee.org>
parents: 5843
diff changeset
1274 in the output of a GET add the query parameter
5824
352e78c3b4ab Allow @fields to include protected properties, document @protected
John Rouillard <rouilj@ieee.org>
parents: 5738
diff changeset
1275 ``@protected=true`` to the query and attributes like: actor,
352e78c3b4ab Allow @fields to include protected properties, document @protected
John Rouillard <rouilj@ieee.org>
parents: 5738
diff changeset
1276 created, creator and activity will be include in the result.
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1277
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1278 Link and Multilink properties are displayed as a dictionary with a
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1279 ``link`` and an ``id`` property by default. This is controlled by the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1280 ``@verbose`` attribute which is set to 1 by default. If set to 0, only
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1281 the id is shown for Link and Multilink attributes. In this form, the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1282 data can be modified and sent back using ``PUT`` to change the item.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1283 If set to 2, the label property (usually ``name`` e.g. for status) is
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1284 also put into the dictionary. Content properties of message and file
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1285 object are by default also shown as a dictionary with a sole link
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1286 attribute. The link is the download link for the file or message. If
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1287 @verbose is >= 3, the content property is shown in json as a (possibly
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1288 very long) string. Currently the json serializer cannot handle files
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1289 not properly utf-8 encoded, so specifying @verbose=3 for files is
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1290 currently discouraged.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1291
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1292 An example of returned values::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1293
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1294 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1295 "data": {
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1296 "type": "issue",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1297 "@etag": "\"f15e6942f00a41960de45f9413684591\"",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1298 "link": "https://.../rest/data/issue/23",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1299 "attributes": {
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1300 "keyword": [],
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1301 "messages": [
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1302 {
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1303 "link": "https://.../rest/data/msg/375",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1304 "id": "375"
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1305 },
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1306 {
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1307 "link": "https://.../rest/data/msg/376",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1308 "id": "376"
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1309 },
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1310 ...
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1311 ],
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1312 "files": [],
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1313 "status": {
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1314 "link": "https://.../rest/data/status/2",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1315 "id": "2"
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1316 },
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1317 "title": "This is a title title",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1318 "superseder": [],
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1319 "nosy": [
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1320 {
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1321 "link": "https://.../rest/data/user/4",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1322 "id": "4"
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1323 },
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1324 {
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1325 "link": "https://.../rest/data/user/5",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1326 "id": "5"
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1327 }
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1328 ],
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1329 "assignedto": null,
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1330 },
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1331 "id": "23"
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1332 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1333 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1334
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1335 Retrieve item using key value
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
1336 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1337
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1338 If the class has a key attribute, e.g. the 'status' class in the
5895
93bbe5340d5b More typo fixes and verbatim blocks.
John Rouillard <rouilj@ieee.org>
parents: 5894
diff changeset
1339 classic tracker, it can be used to retrieve the item.
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1340
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1341 You can get an individual status by specifying the key-attribute value
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1342 e.g. ``/data/status/name=closed``. Note that ``name`` in this example
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1343 must be the key-attribute of the class. A short-form (which might not
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1344 be supported in future version of the API) is to specify only the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1345 value, e.g. ``/data/status/closed``. This short-form only works when
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1346 you're sure that the key of the class is not numeric. E.G. if the name
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1347 was "7", /data/status/7 would return the status with id 7 not the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1348 status with name "7". To get the status with name 7, you must use
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1349 the long form /data/status/name=7
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1350
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1351 The long-form (with ``=``) is different from a query-parameter like
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1352 ``/data/status?name=closed`` which would find all stati (statuses)
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1353 that have ``closed`` as a substring.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1354
5928
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1355 Dealing with Messages and Files
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
1356 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5928
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1357
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1358 Using the requests library you can upload a file using::
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1359
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1360 d = dict (name = filename, content = content, type = content_type)
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1361 j = self.post ('file', data = d)
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1362
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1363 Instead of specifying json = dictionary we specify data = dictionary
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1364 as shown above. (We believe) this encodes the contents using
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1365 application/x-www-form-urlencoded which is not optimal for large files
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1366 due to the encoding overhead.
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1367
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1368 The requests library can use multipart/form-data which is more
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1369 efficient for large files. To do this specify both, files= *and* data=
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1370 parameters, e.g.::
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1371
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1372 # A binary string that can't be decoded as unicode
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1373 url = 'https://.../demo/rest/data/'
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1374 content = open ('random-junk', 'rb').read ()
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1375 fname = 'a-bigger-testfile'
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1376 d = dict(name = fname, type='application/octet-stream')
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1377 c = dict (content = content)
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1378 r = session.post (url + 'file', files = c, data = d)
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1379
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1380 Curl can be used to post a file using multipart/form-data with::
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1381
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1382 curl -u demo:demo -s -X POST -H "Referer: https://.../demo/" \
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1383 -H "X-requested-with: rest" \
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1384 -F "name=afile" -F "type=image/vnd.microsoft.icon" \
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1385 -F "content=@doc/roundup-favicon.ico" \
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1386 https://.../demo/rest/data/file
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1387
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1388 the file is located at doc/roundup-favicon.ico. These calls will
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1389 return something like::
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1390
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1391 {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1392 "data": {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1393 "id": "12",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1394 "link": "https://.../demo/rest/data/file/12"
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1395 }
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1396 }
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1397
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1398
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1399 Other Supported Methods for Items
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
1400 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1401
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1402 The method ``PUT`` is allowed on individual items, e.g.
8218
32aaf5dc562b fix(REST): issue2551383; improve errors for bad json, fix PUT docs
John Rouillard <rouilj@ieee.org>
parents: 8212
diff changeset
1403 ``/data/issue/42`` On success it returns a data structure similar to
32aaf5dc562b fix(REST): issue2551383; improve errors for bad json, fix PUT docs
John Rouillard <rouilj@ieee.org>
parents: 8212
diff changeset
1404 the respective ``GET`` method. However it is only concerned with the
32aaf5dc562b fix(REST): issue2551383; improve errors for bad json, fix PUT docs
John Rouillard <rouilj@ieee.org>
parents: 8212
diff changeset
1405 changes that have occurred. Since it is not a full ``GET`` request, it
32aaf5dc562b fix(REST): issue2551383; improve errors for bad json, fix PUT docs
John Rouillard <rouilj@ieee.org>
parents: 8212
diff changeset
1406 doesn't include an etag or unchanged attributes. Note that for ``PUT``
32aaf5dc562b fix(REST): issue2551383; improve errors for bad json, fix PUT docs
John Rouillard <rouilj@ieee.org>
parents: 8212
diff changeset
1407 an Etag has to be supplied, either in the request header or as an
32aaf5dc562b fix(REST): issue2551383; improve errors for bad json, fix PUT docs
John Rouillard <rouilj@ieee.org>
parents: 8212
diff changeset
1408 @etag parameter. An example::
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1409
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1410 curl -u admin:admin -X PUT \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1411 --header 'Referer: https://example.com/demo/' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1412 --header 'X-Requested-With: rest' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1413 --header "Content-Type: application/json" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1414 --header "Accept: application/json" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1415 --header 'If-Match: "dd41f02d6f8b4c34b439fc712b522fb3"' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1416 --data '{ "nosy": [ "1", "5" ] }' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1417 "https://example.com/demo/rest/data/issue/23"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1418
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1419 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1420 "data": {
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1421 "attribute": {
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1422 "nosy": [
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1423 "1",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1424 "5"
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1425 ]
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1426 },
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1427 "type": "issue",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1428 "link": "https://example.com/demo/rest/data/issue/23",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1429 "id": "23"
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1430 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1431 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1432
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1433 If the above command is repeated with the data attribute::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1434
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1435 --data '{ "nosy": [ "1", "5" ], "title": "This is now my title" }'
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1436
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1437 this is returned::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1438
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1439 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1440 "data": {
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1441 "attribute": {
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1442 "title": "This is now my title"
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1443 },
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1444 "type": "issue",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1445 "link":
5928
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1446 "https://.../demo/rest/data/issue/23",
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1447 "id": "23"
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1448 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1449 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1450
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1451 Note that nosy is not in the attributes returned. It is the same as
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1452 before, so no change has happened and it is not reported.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1453 Changing both nosy and title::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1454
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1455 curl -u admin:admin -X PUT \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1456 --header 'Referer: https://.../' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1457 --header 'X-Requested-With: rest' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1458 --header "Content-Type: application/json" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1459 --header "Accept: application/json" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1460 --header 'If-Match: "8209add59a79713d64f4d1a072aef740"' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1461 --data '{ "nosy": [ "4", "5" ], "title": "This is now my new title" }' \
5928
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1462 "https://.../demo/rest/data/issue/23"
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1463
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1464 which returns both title and nosy attributes::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1465
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1466 {
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1467 "data": {
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1468 "attribute": {
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1469 "title": "This is now my new title",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1470 "nosy": [
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1471 "4",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1472 "5"
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1473 ]
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1474 },
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1475 "type": "issue",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1476 "link":
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1477 "https://.../demo/rest/data/issue/23",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1478 "id": "23"
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1479 }
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1480 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1481
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1482 Note that mixing url query parameters with payload submission doesn't
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1483 work. So using::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1484
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1485 https://.../rest/data/issue/23?@pretty=false
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1486
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1487 doesn't have the desired effect. However it can be put in the data
5895
93bbe5340d5b More typo fixes and verbatim blocks.
John Rouillard <rouilj@ieee.org>
parents: 5894
diff changeset
1488 payload::
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1489
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1490 curl -u admin:admin ...
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1491 --data '{ "nosy": [ "4", "5" ], "title": "...", "@pretty": "false" }'
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1492
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1493 produces::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1494
5892
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
1495 {"data": {"attribute": {...}, "type": "issue",
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1496 "link": "https://...", "id": "23"}}
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1497
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1498 the lines are wrapped for display purposes, in real life it's one long
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1499 line.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1500
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1501 The method ``DELETE`` is allowed on items, e.g., ``/data/issue/42``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1502 and will retire (mark as deleted) the respective item. On success it
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1503 will only return a status code. The item is still available if
5895
93bbe5340d5b More typo fixes and verbatim blocks.
John Rouillard <rouilj@ieee.org>
parents: 5894
diff changeset
1504 accessed directly by its item url. The item will not show up in
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1505 searches where it would have been matched if not retired.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1506
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1507 Finally the ``PATCH`` method can be applied to individual items, e.g.,
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1508 ``/data/issue/42``. This method gets an operator ``@op=<method>``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1509 where ``<method>`` is one of ``add``, ``replace``, ``remove``. For
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1510 items, an additional operator ``action`` is supported. If no operator
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1511 is specified, the default is ``replace``. The first three operators
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1512 are self explanatory. For an ``action`` operator an ``@action_name``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1513 and optional ``@action_argsXXX`` parameters have to be
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1514 supplied. Currently there are only two actions, neither has args,
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1515 namely ``retire`` and ``restore``. The ``retire`` action on an item is
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1516 the same as a ``DELETE`` method, it retires the item. The ``restore``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1517 action is the inverse of ``retire``, the item is again visible. On
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1518 success the returned value is the same as the respective ``GET``
5895
93bbe5340d5b More typo fixes and verbatim blocks.
John Rouillard <rouilj@ieee.org>
parents: 5894
diff changeset
1519 method. An example to add a user to the nosy list of an item is::
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1520
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1521 curl -u admin:admin -p -X PATCH \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1522 --header "Content-Type: application/x-www-form-urlencoded" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1523 --header "Accept: application/json" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1524 --header 'If-Match: "c6e2d81019acff1da7a2da45f93939bd"' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1525 --data-urlencode '@op=add' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1526 --data 'nosy=3' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1527 "https://.../rest/data/issue/23"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1528
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1529 which returns::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1530
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1531 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1532 "data": {
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1533 "attribute": {
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1534 "nosy": [
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1535 "3",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1536 "4"
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1537 ]
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1538 },
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1539 "type": "issue",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1540 "link": "https://.../rest/data/issue/23",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1541 "id": "23"
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1542 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1543 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1544
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1545 Note that the changed values are returned so you can update
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1546 internal state in your app with the new data.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1547
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1548 The ``GET`` method on an item (e.g. ``/data/issue/43``) returns an
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1549 ETag in the http header *and* the ``@etag`` value in the json
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1550 payload. When modifying a property via ``PUT`` or ``PATCH`` or
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1551 ``DELETE`` the etag value for the item must be supplied using an
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1552 ``If-Match`` header. If you are using ``PUT`` or ``PATCH`` an
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1553 ``@etag`` value can be supplied in the payload in place of the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1554 ``If-Match`` header.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1555
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1556 /data/\ *class*/\ *id*/\ *property* field
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
1557 -----------------------------------------
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1558
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1559 A ``GET`` method on a property (e.g. ``/data/issue/42/title``) returns the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1560 link, an ``@etag``, the type of the property (e.g. "<type str>") the id
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1561 of the item and the content of the property in ``data``.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1562
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1563 For example::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1564
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1565 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1566 "data": {
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1567 "link": "https://.../rest/data/issue/22/title",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1568 "data": "I need Broken PC",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1569 "type": "<class 'str'>",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1570 "id": "22",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1571 "@etag": "\"370510512b2d8fc3f98aac3d762cc7b1\""
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1572 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1573 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1574
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1575
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1576 All endpoints support an ``OPTIONS`` method for determining which
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1577 methods are allowed on a given endpoint.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1578
5928
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1579 Message and File Content
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
1580 ~~~~~~~~~~~~~~~~~~~~~~~~
5928
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1581
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1582 Messages and files have content properties. If the data is utf-8
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1583 compatible (e.g. an email message) you can retrieve it with
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1584 rest/data/msg/11/content to obtain::
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1585
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1586 {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1587 "data": {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1588 "id": "11",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1589 "type": "<class 'str'>",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1590 "link": "https://.../demo/rest/data/msg/11/content",
6764
32f52d14b496 Typo fixes, formatting fixes, jwt -> JWT, add link to JWT issue
John Rouillard <rouilj@ieee.org>
parents: 6681
diff changeset
1591 "data": "of has to who pleasure. or of account give because the
32f52d14b496 Typo fixes, formatting fixes, jwt -> JWT, add link to JWT issue
John Rouillard <rouilj@ieee.org>
parents: 6681
diff changeset
1592 reprehenderit\neu to quisquam velit, passage, was or...",
5928
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1593 "@etag": "\"584f82231079e349031bbb853747df1c\""
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1594 }
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1595 }
5928
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1596
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1597 (the content property is wrapped for display, it is one long line.)
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1598
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1599 .. _binary_content property:
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1600
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1601 If the data is not representable in utf-8, you need to use the
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1602 binary_content
5930
cc6891ea1f01 issue2551067 make url into liternal not clickble.
John Rouillard <rouilj@ieee.org>
parents: 5929
diff changeset
1603 property. E.G. ``https://.../demo/rest/data/file/11/binary_content``
5928
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1604 returns::
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1605
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1606 {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1607 "data": {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1608 "id": "11",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1609 "type": "<class 'bytes'>",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1610 "link": "https://.../demo/rest/data/file/11/binary_content",
5929
0368d75de544 issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents: 5928
diff changeset
1611 "data": "b'\\x00\\x00\\x01\\x00\\x01...\\xec?\\x00\\x00'",
5928
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1612 "@etag": "\"74276f75ef71a30a0cce62dc6a8aa1bb\""
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1613 }
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1614 }
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1615
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1616 (data field elided for display). You can also receive the file content
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1617 as a data stream rather than encoded. See `Getting Message and Files
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1618 Content`_.
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1619
5929
0368d75de544 issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents: 5928
diff changeset
1620 The data is a json encoded hexidecimal representation of the data.
0368d75de544 issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents: 5928
diff changeset
1621
5928
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1622
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1623 Other Supported Methods for fields
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
1624 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1625
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1626 The method ``PUT`` is allowed on a property e.g.,
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1627 ``/data/issue/42/title``. On success it returns the same parameters as
8218
32aaf5dc562b fix(REST): issue2551383; improve errors for bad json, fix PUT docs
John Rouillard <rouilj@ieee.org>
parents: 8212
diff changeset
1628 the respective ``PUT`` method on the item. For example::
32aaf5dc562b fix(REST): issue2551383; improve errors for bad json, fix PUT docs
John Rouillard <rouilj@ieee.org>
parents: 8212
diff changeset
1629
32aaf5dc562b fix(REST): issue2551383; improve errors for bad json, fix PUT docs
John Rouillard <rouilj@ieee.org>
parents: 8212
diff changeset
1630 {
32aaf5dc562b fix(REST): issue2551383; improve errors for bad json, fix PUT docs
John Rouillard <rouilj@ieee.org>
parents: 8212
diff changeset
1631 "data": {
32aaf5dc562b fix(REST): issue2551383; improve errors for bad json, fix PUT docs
John Rouillard <rouilj@ieee.org>
parents: 8212
diff changeset
1632 "id": "42",
32aaf5dc562b fix(REST): issue2551383; improve errors for bad json, fix PUT docs
John Rouillard <rouilj@ieee.org>
parents: 8212
diff changeset
1633 "type": "issue",
32aaf5dc562b fix(REST): issue2551383; improve errors for bad json, fix PUT docs
John Rouillard <rouilj@ieee.org>
parents: 8212
diff changeset
1634 "link": "https://.../demo/rest/data/issue/42",
32aaf5dc562b fix(REST): issue2551383; improve errors for bad json, fix PUT docs
John Rouillard <rouilj@ieee.org>
parents: 8212
diff changeset
1635 "attribute": {
32aaf5dc562b fix(REST): issue2551383; improve errors for bad json, fix PUT docs
John Rouillard <rouilj@ieee.org>
parents: 8212
diff changeset
1636 "title": "this is a new title"
32aaf5dc562b fix(REST): issue2551383; improve errors for bad json, fix PUT docs
John Rouillard <rouilj@ieee.org>
parents: 8212
diff changeset
1637 }
32aaf5dc562b fix(REST): issue2551383; improve errors for bad json, fix PUT docs
John Rouillard <rouilj@ieee.org>
parents: 8212
diff changeset
1638 }
32aaf5dc562b fix(REST): issue2551383; improve errors for bad json, fix PUT docs
John Rouillard <rouilj@ieee.org>
parents: 8212
diff changeset
1639 }
32aaf5dc562b fix(REST): issue2551383; improve errors for bad json, fix PUT docs
John Rouillard <rouilj@ieee.org>
parents: 8212
diff changeset
1640
32aaf5dc562b fix(REST): issue2551383; improve errors for bad json, fix PUT docs
John Rouillard <rouilj@ieee.org>
parents: 8212
diff changeset
1641 If the new value for the title was the same as on the server, the
32aaf5dc562b fix(REST): issue2551383; improve errors for bad json, fix PUT docs
John Rouillard <rouilj@ieee.org>
parents: 8212
diff changeset
1642 attribute property would be empty since the value was not changed.
32aaf5dc562b fix(REST): issue2551383; improve errors for bad json, fix PUT docs
John Rouillard <rouilj@ieee.org>
parents: 8212
diff changeset
1643 Note that for ``PUT`` an Etag has to be
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1644 supplied, either in the request header or as an @etag parameter.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1645 Example using multipart/form-data rather than json::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1646
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1647 curl -vs -u provisional:provisional -X PUT \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1648 --header "Accept: application/json" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1649 --data "data=Provisional" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1650 --header "If-Match: 079eba599152f3eed00567e23258fecf" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1651 --data-urlencode "@etag=079eba599152f3eed00567e23258fecf" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1652 "https://.../rest/data/user/5/realname"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1653
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1654 This example updates a leadtime field that is declared as an interval
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1655 type::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1656
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1657 curl -vs -u demo:demo -X PUT \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1658 --header "Accept: application/json" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1659 --header 'Content-Type: application/json' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1660 --header "Referer: https://.../" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1661 --header "x-requested-with: rest" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1662 --header 'If-Match: "e2e6cc43c3475a4a3d9e5343617c11c3"' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1663 --data '{"leadtime": "2d" }' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1664 "https://.../rest/data/issue/10"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1665
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1666 It is also possible to call ``DELETE`` on a
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1667 property of an item, e.g., ``/data/issue/42/nosy`` to delete the nosy
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1668 list. The same effect can be achieved with a ``PUT`` request and an
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1669 empty new value. This may fail if the property is required.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1670
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1671 The ``PATCH`` method can be applied to properties, e.g.,
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1672 ``/data/issue/42/title``. This method gets an operator
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1673 ``@op=<method>`` where ``<method>`` is one of ``add``, ``replace``,
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1674 ``remove``. If no operator is specified, the default is ``replace``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1675 which is the same as performing a PUT on the field url. ``add`` and
5854
d5aed7106ee6 Need to fix spelling.
John Rouillard <rouilj@ieee.org>
parents: 5843
diff changeset
1676 ``remove`` allow adding and removing values from MultiLink
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1677 properties. This is easier than having to rewrite the entire value for
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1678 the field using the ``replace`` operator or doing a PUT to the field.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1679 On success the returned value is the same as the respective ``GET``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1680 method.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1681
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1682 The ``GET`` method on an item (e.g. ``/data/issue/43``) returns an
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1683 ETag in the http header *and* the ``@etag`` value in the json
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1684 payload. When modifying a property via ``PUT`` or ``PATCH`` or
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1685 ``DELETE`` the etag value for the item must be supplied using an
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1686 ``If-Match`` header. If you are using ``PUT`` or ``PATCH`` an
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1687 ``@etag`` value can be supplied in the payload in place of the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1688 ``If-Match`` header.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1689
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1690 Tunneling Methods via POST
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
1691 --------------------------
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1692
7455
f53de10ea8ea Fix grammar.
John Rouillard <rouilj@ieee.org>
parents: 7361
diff changeset
1693 If you are working through a proxy and unable to use http methods like
f53de10ea8ea Fix grammar.
John Rouillard <rouilj@ieee.org>
parents: 7361
diff changeset
1694 PUT, PATCH, or DELETE, you can use POST to perform the action. To tunnel
5854
d5aed7106ee6 Need to fix spelling.
John Rouillard <rouilj@ieee.org>
parents: 5843
diff changeset
1695 an action through POST, send the ``X-HTTP-METHOD-OVERRIDE`` header
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1696 with a value of DELETE or other capitalized HTTP verb. The body of the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1697 POST should be what you would send if you were using the method
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1698 without tunneling.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1699
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1700 Examples and Use Cases
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
1701 ======================
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1702
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1703 sample python client
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
1704 --------------------
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1705
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1706 The client uses the python ``requests`` library for easier interaction
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1707 with a REST API supporting JSON encoding::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1708
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1709
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1710 >>> import requests
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1711 >>> u = 'http://user:password@tracker.example.com/demo/rest/data/'
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1712 >>> s = requests.session()
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1713 >>> session.auth = ('admin', 'admin')
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1714 >>> r = s.get(u + 'issue/42/title')
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1715 >>> if r.status_code != 200:
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1716 ... print("Failed: %s: %s" % (r.status_code, r.reason))
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1717 ... exit(1)
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1718 >>> print (r.json() ['data']['data']
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1719 TEST Title
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1720 >>> h = {'X-Requested-With': 'rest', 'Referer': 'http://tracker.example.com/demo/'}
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1721 >>> r = s.post (u + 'issue', data = dict (title = 'TEST Issue'), headers=h)
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1722 >>> if not 200 <= r.status_code <= 201:
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1723 ... print("Failed: %s: %s" % (r.status_code, r.reason))
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1724 ... exit(1)
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1725 >>> print(r.json())
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1726
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1727 Retire/Restore::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1728 >>> r = s.delete (u + 'issue/42')
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1729 >>> print (r.json())
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1730 >>> r = s.get (u + 'issue/42')
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1731 >>> etag = r.headers['ETag']
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1732 >>> print("ETag: %s" % etag)
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1733 >>> etag = r.json()['data']['@etag']
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1734 >>> print("@etag: %s" % etag)
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1735 >>> h = {'If-Match': etag,
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1736 ... 'X-Requested-With': 'rest',
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1737 ... 'Referer': 'http://tracker.example.com/demo/'}
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1738 >>> d = {'@op:'action', '@action_name':'retire'}
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1739 >>> r = s.patch(u + 'issue/42', data = d, headers = h)
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1740 >>> print(r.json())
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1741 >>> d = {'@op:'action', '@action_name':'restore'}
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1742 >>> r = s.patch(u + 'issue/42', data = d, headers = h)
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1743 >>> print(r.json())
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1744
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1745 Note the addition of headers for: x-requested-with and referer. This
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1746 allows the request to pass the CSRF protection mechanism. You may need
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1747 to add an Origin header if this check is enabled in your tracker's
6674
ff8845ca305e issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents: 6630
diff changeset
1748 config.ini (look for csrf_enforce_header_origin). (Note the Origin
ff8845ca305e issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents: 6630
diff changeset
1749 header check may have to be disabled if an application is making a
6764
32f52d14b496 Typo fixes, formatting fixes, jwt -> JWT, add link to JWT issue
John Rouillard <rouilj@ieee.org>
parents: 6681
diff changeset
1750 CORS request to the Roundup server. If you have this issue, please
32f52d14b496 Typo fixes, formatting fixes, jwt -> JWT, add link to JWT issue
John Rouillard <rouilj@ieee.org>
parents: 6681
diff changeset
1751 contact the Roundup team using the mailing lists as this is a bug.)
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1752
6204
e77f6d00cfb9 Fix display formatting.
John Rouillard <rouilj@ieee.org>
parents: 6194
diff changeset
1753 A similar curl based retire example is to use::
5933
0bac8b9a0ecc Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents: 5930
diff changeset
1754
0bac8b9a0ecc Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents: 5930
diff changeset
1755 curl -s -u admin:admin \
0bac8b9a0ecc Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents: 5930
diff changeset
1756 -H "Referer: https://tracker.example.com/demo/" \
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1757 -H "X-requested-with: rest" \
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1758 -H "Content-Type: application/json" \
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1759 https://tracker.example.com/demo/rest/data/status/1
5933
0bac8b9a0ecc Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents: 5930
diff changeset
1760
0bac8b9a0ecc Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents: 5930
diff changeset
1761 to get the etag manually. Then insert the etag in the If-Match header
0bac8b9a0ecc Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents: 5930
diff changeset
1762 for this retire example::
0bac8b9a0ecc Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents: 5930
diff changeset
1763
0bac8b9a0ecc Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents: 5930
diff changeset
1764 curl -s -u admin:admin \
0bac8b9a0ecc Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents: 5930
diff changeset
1765 -H "Referer: https://tracker.example.com/demo/" \
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1766 -H "X-requested-with: rest" \
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1767 -H "Content-Type: application/json" \
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1768 -H 'If-Match: "a502faf4d6b8e3897c4ecd66b5597571"' \
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1769 --data-raw '{ "@op":"action", "@action_name": "retire" }'\
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1770 -X PATCH \
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1771 https://tracker.example.com/demo/rest/data/status/1
5933
0bac8b9a0ecc Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents: 5930
diff changeset
1772
0bac8b9a0ecc Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents: 5930
diff changeset
1773 and restore::
0bac8b9a0ecc Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents: 5930
diff changeset
1774
0bac8b9a0ecc Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents: 5930
diff changeset
1775 curl -s -u admin:admin \
0bac8b9a0ecc Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents: 5930
diff changeset
1776 -H "Referer: https://tracker.example.com/demo/" \
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1777 -H "X-requested-with: rest" \
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1778 -H "Content-Type: application/json" \
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1779 -H 'If-Match: "a502faf4d6b8e3897c4ecd66b5597571"' \
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1780 --data-raw '{ "@op":"action", "@action_name": "restore" }'\
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1781 -X PATCH \
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1782 https://tracker.example.com/demo/rest/data/status/1
5933
0bac8b9a0ecc Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents: 5930
diff changeset
1783
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
1784
5677
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1785 Searches and selection
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
1786 ----------------------
5677
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1787
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1788 One difficult interface issue is selection of items from a long list.
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1789 Using multi-item selects requires loading a lot of data (e.g. consider
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1790 a selection tool to select one or more issues as in the classic
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1791 superseder field).
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1792
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1793 This can be made easier using javascript selection tools like select2,
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1794 selectize.js, chosen etc. These tools can query a remote data provider
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1795 to get a list of items for the user to select from.
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1796
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1797 Consider a multi-select box for the superseder property. Using
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
1798 selectize.js (and jquery) code similar to::
5677
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1799
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
1800 $('#superseder').selectize({
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1801 valueField: 'id',
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1802 labelField: 'title',
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1803 searchField: 'title', ...
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1804 load: function(query, callback) {
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1805 if (!query.length) return callback();
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1806 $.ajax({
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1807 url: '.../rest/data/issue?@verbose=2&title='
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1808 + encodeURIComponent(query),
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1809 type: 'GET',
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1810 error: function() {callback();},
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1811 success: function(res) {
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1812 callback(res.data.collection);}
5677
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1813
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1814 Sets up a box that a user can type the word "request" into. Then
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1815 selectize.js will use that word to generate an ajax request with the
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
1816 url: ``.../rest/data/issue?@verbose=2&title=request``
5677
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1817
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
1818 This will return data like::
5677
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1819
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1820 {
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1821 "data": {
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1822 "@total_size": 440,
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1823 "collection": [
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1824 {
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1825 "link": ".../rest/data/issue/8",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1826 "id": "8",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1827 "title": "Request for Power plugs"
5677
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1828 },
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1829 {
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1830 "link": ".../rest/data/issue/27",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1831 "id": "27",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1832 "title": "Request for foo"
5677
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1833 },
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
1834 ...
5677
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1835
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1836 selectize.js will look at these objects (as passed to
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1837 callback(res.data.collection)) and create a select list from the each
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1838 object showing the user the labelField (title) for each object and
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1839 associating each title with the corresponding valueField (id). The
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1840 example above has 440 issues returned from a total of 2000
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1841 issues. Only 440 had the word "request" somewhere in the title greatly
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1842 reducing the amount of data that needed to be transferred.
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1843
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
1844 Similar code can be set up to search a large list of keywords using::
5677
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1845
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1846 .../rest/data/keyword?@verbose=2&name=some
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1847
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1848 which would return: "some keyword" "awesome" "somebody" making
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1849 selections for links and multilinks much easier.
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1850
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1851 A get on a collection endpoint can include other properties. Why do we
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1852 want this? Selectize.js can set up option groups (optgroups) in the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1853 select pulldown. So by including status in the returned data using
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1854 a url like ``https://.../rest/data/issue?@verbose=2&@fields=status``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1855 we get::
5677
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1856
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1857 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1858 "link": "https://.../rest/data/issue/1001",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1859 "title": "Request for Broken PC",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1860 "id": "1001",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1861 "status": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1862 "link": "https://.../rest/data/status/6",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1863 "id": "6",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1864 "name": "resolved"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1865 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1866 }
5677
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1867
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
1868 a select widget like::
5677
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1869
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1870 === New ===
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1871 A request
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1872 === Open ===
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1873 Request for bar
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1874 Request for foo
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1875
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1876 etc. can be generated. Also depending on the javascript library, other
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1877 fields can be used for subsearch and sorting.
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1878
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1879
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1880 Programming the REST API
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
1881 ========================
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1882
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1883 You can extend the rest api for a tracker. This describes how to add
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1884 new rest end points. At some point it will also describe the rest.py
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1885 structure and implementation.
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1886
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1887 Adding new rest endpoints
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
1888 -------------------------
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1889
6765
b4bfbd768bc1 How to add dicttoxml at system or tracker level.
John Rouillard <rouilj@ieee.org>
parents: 6764
diff changeset
1890 Add or edit the file `interfaces.py`_ at the root of the tracker
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1891 directory.
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1892
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1893 In that file add::
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1894
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1895 from roundup.rest import Routing, RestfulInstance, _data_decorator
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1896 from roundup.exceptions import Unauthorised
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1897
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1898 class RestfulInstance:
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1899
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1900 @Routing.route("/summary2")
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1901 @_data_decorator
8563
909cf30c01c1 doc: rename input in examples to input_payload
John Rouillard <rouilj@ieee.org>
parents: 8543
diff changeset
1902 def summary2(self, input_payload):
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1903 result = { "hello": "world" }
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1904 return 200, result
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1905
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1906 will make a new endpoint .../rest/summary2 that you can test with::
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1907
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1908 $ curl -X GET .../rest/summary2
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1909 {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1910 "data": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1911 "hello": "world"
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1912 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1913 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1914
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1915 Similarly appending this to interfaces.py after summary2::
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1916
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1917 # handle more endpoints
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1918 @Routing.route("/data/<:class_name>/@schema", 'GET')
8563
909cf30c01c1 doc: rename input in examples to input_payload
John Rouillard <rouilj@ieee.org>
parents: 8543
diff changeset
1919 def get_element_schema(self, class_name, input_payload):
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1920 result = { "schema": {} }
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1921 uid = self.db.getuid ()
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1922 if not self.db.security.hasPermission('View', uid, class_name) :
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1923 raise Unauthorised('Permission to view %s denied' % class_name)
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1924
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1925 class_obj = self.db.getclass(class_name)
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1926 props = class_obj.getprops(protected=False)
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1927 schema = result['schema']
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1928
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1929 for prop in props:
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1930 schema[prop] = { "type": repr(class_obj.properties[prop]) }
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1931
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1932 return result
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1933
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1934 ..
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1935 the # comment in the example is needed to preserve indention under Class.
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1936
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1937 returns some data about the class::
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1938
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1939 $ curl -X GET .../rest/data/issue/@schema
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1940 {
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1941 "schema": {
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1942 "keyword": {
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1943 "type": "<roundup.hyperdb.Multilink to \"keyword\">"
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1944 },
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1945 "title": {
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1946 "type": "<roundup.hyperdb.String>"
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1947 },
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1948 "files": {
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1949 "type": "<roundup.hyperdb.Multilink to \"file\">"
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1950 },
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1951 "status": {
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1952 "type": "<roundup.hyperdb.Link to \"status\">"
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1953 }, ...
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
1954 }
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1955 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1956
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1957
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1958 Adding other endpoints (e.g. to allow an OPTIONS query against
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1959 ``/data/issue/@schema``) is left as an exercise for the reader.
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1960
5883
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1961 Redefine/move rest endpoints
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
1962 ----------------------------
5883
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1963
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1964 In addition to adding new endpoints, you can redefine existing
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1965 endpoints. Adding this as described above::
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1966
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1967 @Routing.route("/summary")
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1968 @_data_decorator
8563
909cf30c01c1 doc: rename input in examples to input_payload
John Rouillard <rouilj@ieee.org>
parents: 8543
diff changeset
1969 def summary2(self, input_payload):
5883
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1970 result = { "hello": "world" }
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1971 return 200, result
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1972
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1973 will return::
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1974
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1975 {
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1976 "data": {
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1977 "hello": "world"
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1978 }
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1979 }
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1980
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1981
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1982 In addition to overriding existing endpoints, you can move existing
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1983 endpoints to new locations. Adding::
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1984
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1985 @Routing.route("/data2/<:classname>")
8563
909cf30c01c1 doc: rename input in examples to input_payload
John Rouillard <rouilj@ieee.org>
parents: 8543
diff changeset
1986 def get_collection2(self, classname, input_payload):
5883
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1987 """ Remap existing function in rest.py to a new endpoint
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1988
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1989 Existing function is decorated with:
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1990
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1991 @Routing.route("/data/<:classname>")
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1992 @_data_decorator
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1993
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1994 so we need to drop @_data_decorator from this function since
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1995 we can't apply @_data_decorator twice.
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1996 """
8563
909cf30c01c1 doc: rename input in examples to input_payload
John Rouillard <rouilj@ieee.org>
parents: 8543
diff changeset
1997 return self.get_collection(classname, input_payload)
5883
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1998
5886
f4e77d446add Clarify text.
John Rouillard <rouilj@ieee.org>
parents: 5885
diff changeset
1999 will make the response at /rest/data2/<class> be the same as what is
f4e77d446add Clarify text.
John Rouillard <rouilj@ieee.org>
parents: 5885
diff changeset
2000 normally at /rest/data/<class>.
5883
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
2001
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
2002
5843
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2003 Controlling Access to Backend Data
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
2004 ----------------------------------
5843
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2005
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2006 Roundup's schema is the primary access control mechanism. Roles and
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2007 Permissions provide the ability to carefully control what data can be
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2008 seen.
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2009
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2010 However the templating system can access the hyperdb directly which
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2011 allows filtering to happen with admin privs escaping the standard
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2012 permissions scheme. For example access to a user's roles should be
7499
a072331c843b Change customizing to customising in all variants.
John Rouillard <rouilj@ieee.org>
parents: 7473
diff changeset
2013 limited to the user (read only) and an admin. If you have customised
5843
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2014 your schema to implement `Restricting the list of
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2015 users that are assignable to a task
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2016 <customizing.html#restricting-the-list-of-users-that-are-assignable-to-a-task>`__
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2017 so that only users with a
5843
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2018 Developer role are allowed to be assigned to an issue, a rest end
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2019 point must be added to provide a view that exposes users with this
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2020 permission.
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2021
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2022 Using the normal ``/data/user?roles=Developer`` will return all the
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2023 users in the system unless you are an admin user because most users
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2024 can't see the roles. Building on the `Adding new rest endpoints`_
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2025 section this code adds a new endpoint ``/data/@permission/Developer``
5843
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2026 that returns a list of users with the developer role::
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2027
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2028 from roundup.rest import Routing, RestfulInstance
7582
978285986b2c fix: issue2551193 - Fix roundup for removal of cgi and cgitb ...
John Rouillard <rouilj@ieee.org>
parents: 7556
diff changeset
2029 from roundup.anypy.cgi_ import MiniFieldStorage
5843
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2030
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2031 class RestfulInstance(object):
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2032
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2033 @Routing.route("/data/@permission/Developer")
8563
909cf30c01c1 doc: rename input in examples to input_payload
John Rouillard <rouilj@ieee.org>
parents: 8543
diff changeset
2034 def get_role_Developer(self, input_payload):
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2035 '''An endpoint to return a list of users with Developer
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2036 role who can be assigned to an issue.
5843
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2037
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2038 It ignores attempt to search by any property except
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2039 username and realname. It also ignores the whole @fields
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2040 specification if it specifies a property the user
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2041 can't view. Other @ query params (e.g. @page... and
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2042 @verbose) are supported.
5843
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2043
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2044 It assumes admin access rights so that the roles property
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2045 of the user can be searched. This is needed if the roles
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2046 property is not searchable/viewable by normal users. A user
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2047 who can search roles can identify users with the admin
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2048 role. So it does not respond the same as a rest/data/users
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2049 search by a non-admin user.
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2050 '''
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2051 # get real user id
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2052 realuid=self.db.getuid()
5843
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2053
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2054 def allowed_field(fs):
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2055 if fs.name in ['username', 'realname' ]:
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2056 # only allow search matches for these fields
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2057 return True
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2058 elif fs.name in [ '@fields' ]:
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2059 for prop in fs.value.split(','):
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2060 # if any property is unviewable to user, remove
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2061 # @field entry. If they can't see it for the admin
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2062 # user, don't let them see it for any user.
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2063 if not self.db.security.hasPermission(
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2064 'View', realuid, 'user', property=prop,
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2065 itemid='1'):
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2066 return False
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2067 return True
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2068 elif fs.name.startswith("@"):
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2069 # allow @page..., @verbose etc.
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2070 return True
5843
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2071
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2072 # deny all other url parmeters
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2073 return False
5843
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2074
8563
909cf30c01c1 doc: rename input in examples to input_payload
John Rouillard <rouilj@ieee.org>
parents: 8543
diff changeset
2075 # Cleanup input_payload.list to prevent user from probing roles
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2076 # or viewing things the user should not be able to view.
8563
909cf30c01c1 doc: rename input in examples to input_payload
John Rouillard <rouilj@ieee.org>
parents: 8543
diff changeset
2077 input_payload.list[:] = [ fs for fs in input_payload.list
909cf30c01c1 doc: rename input in examples to input_payload
John Rouillard <rouilj@ieee.org>
parents: 8543
diff changeset
2078 if allowed_field(fs) ]
5843
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2079
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2080 # Add the role filter required to implement the permission
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2081 # search
8563
909cf30c01c1 doc: rename input in examples to input_payload
John Rouillard <rouilj@ieee.org>
parents: 8543
diff changeset
2082 input_payload.list.append(MiniFieldStorage("roles", "Developer"))
5843
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2083
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2084 # change user to acquire permission to search roles
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2085 self.db.setCurrentUser('admin')
5843
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2086
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2087 # Once we have cleaned up the request, pass it to
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2088 # get_collection as though /rest/data/users?... has been called
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2089 # to get @verbose and other args supported.
8563
909cf30c01c1 doc: rename input in examples to input_payload
John Rouillard <rouilj@ieee.org>
parents: 8543
diff changeset
2090 return self.get_collection('user', input_payload)
5843
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2091
5895
93bbe5340d5b More typo fixes and verbatim blocks.
John Rouillard <rouilj@ieee.org>
parents: 5894
diff changeset
2092 Calling this with::
93bbe5340d5b More typo fixes and verbatim blocks.
John Rouillard <rouilj@ieee.org>
parents: 5894
diff changeset
2093
93bbe5340d5b More typo fixes and verbatim blocks.
John Rouillard <rouilj@ieee.org>
parents: 5894
diff changeset
2094 curl 'http://example.com/demo/rest/data/@permission/Developer?@fields=realname&roles=Users&@verbose=2'
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2095
5843
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2096 produces output similar to::
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2097
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2098 {
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2099 "data": {
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2100 "collection": [
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2101 {
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2102 "username": "agent",
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2103 "link": http://example.com/demo/rest/data/user/4",
5843
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2104 "realname": "James Bond",
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2105 "id": "4"
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2106 }
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2107 ],
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2108 "@total_size": 1
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2109 }
5843
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2110 }
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2111
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2112 assuming user 4 is the only user with the Developer role. Note that
5895
93bbe5340d5b More typo fixes and verbatim blocks.
John Rouillard <rouilj@ieee.org>
parents: 5894
diff changeset
2113 the url passes the ``roles=User`` filter option which is silently
5843
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2114 ignored.
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2115
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2116 Changing Access Roles with JSON Web Tokens
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
2117 ------------------------------------------
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2118
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2119 As discussed above Roundup's schema is the access control mechanism.
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2120 However you may want to integrate a third party system with roundup.
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2121 E.G. suppose you use a time tracking service that takes an issue id
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2122 and keeps a running count of how much time was spent on it. Then with
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2123 a single button push it can add the recorded time to the roundup
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2124 issue.
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2125
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2126 You probably don't want to give this third party service your roundup
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2127 username and credentials. Especially if your roundup instance is under
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2128 your company's single sign on infrastructure.
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2129
6165
282b611197a1 Typo fix.
John Rouillard <rouilj@ieee.org>
parents: 6090
diff changeset
2130 So what we need is a way for this third party service to impersonate
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2131 you and have access to create a roundup timelog entry (see
7353
fc88c66eb73b format fix.
John Rouillard <rouilj@ieee.org>
parents: 7282
diff changeset
2132 `<customizing.html#adding-a-time-log-to-your-issues>`_). Then add it
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2133 to the associated issue. This should happen without sharing passwords
6166
7e148e988cde Insert missing word.
John Rouillard <rouilj@ieee.org>
parents: 6165
diff changeset
2134 and without allowing the third party service to see the issue (except the
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2135 ``times`` property), user, or other information in the tracker.
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2136
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2137 Enter the use of a JSON web token. Roundup has rudimentary ability to
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2138 manage JWTs and use them for authentication and authorization.
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2139
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2140 There are 5 steps to set this up:
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2141
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2142 1. install pyjwt library using pip or pip3. If roundup can't find the
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2143 jwt module you will see the error ``Support for jwt disabled.``
5892
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
2144 2. create a new role that allows Create access to timelog and edit/view
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2145 access to an issues' ``times`` property.
6764
32f52d14b496 Typo fixes, formatting fixes, jwt -> JWT, add link to JWT issue
John Rouillard <rouilj@ieee.org>
parents: 6681
diff changeset
2146 3. add support for issuing (and validating) JWTs to the rest interface.
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2147 This uses the `Adding new rest endpoints`_ mechanism.
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2148 4. configure roundup's config.ini [web] jwt_secret with at least 32
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2149 random characters of data. (You will get a message
7878
d4aef2b004a1 doc: ad use of openssl rand to generate jwt secret.
John Rouillard <rouilj@ieee.org>
parents: 7854
diff changeset
2150 ``Support for jwt disabled by admin.`` if it's not long
d4aef2b004a1 doc: ad use of openssl rand to generate jwt secret.
John Rouillard <rouilj@ieee.org>
parents: 7854
diff changeset
2151 enough.) If you have openssl installed, you can use the output
d4aef2b004a1 doc: ad use of openssl rand to generate jwt secret.
John Rouillard <rouilj@ieee.org>
parents: 7854
diff changeset
2152 of ``openssl rand -base64 32``.
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2153 5. add an auditor to make sure that users with this role are appending
5892
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
2154 timelog links to the ``times`` property of the issue.
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2155
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2156 Create role
5898
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
2157 ~~~~~~~~~~~
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2158
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2159 Adding this snippet of code to the tracker's ``schema.py`` should
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2160 create a role with the proper authorization::
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2161
5892
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
2162 db.security.addRole(name="User:timelog",
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
2163 description="allow a user to create and append timelogs")
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
2164
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
2165 db.security.addPermissionToRole('User:timelog', 'Rest Access')
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
2166
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2167 perm = db.security.addPermission(name='Create', klass='timelog',
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2168 description="Allow timelog creation", props_only=False)
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2169 db.security.addPermissionToRole("User:timelog", perm)
5892
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
2170
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
2171 perm = db.security.addPermission(name='View', klass='issue',
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2172 properties=('id', 'times'),
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2173 description="Allow retrieving issue etag or timelog issue",
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2174 props_only=False)
5892
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
2175 db.security.addPermissionToRole("User:timelog", perm)
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
2176
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2177 perm = db.security.addPermission(name='Edit', klass='issue',
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2178 properties=('id', 'times'),
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2179 description="Allow editing timelog for issue",
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2180 props_only=False)
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2181 db.security.addPermissionToRole("User:timelog", perm)
5892
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
2182
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
2183 The role is named to work with the /rest/jwt/issue rest endpoint
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
2184 defined below. Starting the role name with ``User:`` allows the jwt
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
2185 issue code to create a token with this role if the user requesting the
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
2186 role has the User role.
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
2187
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
2188 The role *must* have access to the issue ``id`` to retrieve the etag for
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
2189 the issue. The etag is passed in the ``If-Match`` HTTP header when you
5894
45a104bb127e Fix markup.
John Rouillard <rouilj@ieee.org>
parents: 5893
diff changeset
2190 make a call to patch or update the ``times`` property of the issue.
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2191
5892
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
2192 If you use a PATCH rest call with "@op=add" to append the new timelog,
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
2193 you don't need View access to the ``times`` property. If you replace the
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
2194 ``times`` value, you need to read the current value of ``times`` (using
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
2195 View permission), append the newly created timelog id to the (array)
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
2196 value, and replace the ``times`` value.
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
2197
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
2198 Note that the json returned after the operation will include the new
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
2199 value of the ``times`` value so your code can verify that it worked.
8391
e7dc47f4d501 doc: remove potentially, it is incorrect.
John Rouillard <rouilj@ieee.org>
parents: 8326
diff changeset
2200 This leaks info about the previous id's in the field.
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2201
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2202 Create rest endpoints
5898
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
2203 ~~~~~~~~~~~~~~~~~~~~~
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2204
5892
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
2205 Here is code to add to your tracker's ``interfaces.py`` (note code has
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
2206 only been tested with python3)::
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2207
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2208 from roundup.rest import Routing, RestfulInstance, _data_decorator
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2209
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2210 class RestfulInstance(object):
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2211 @Routing.route("/jwt/issue", 'POST')
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2212 @_data_decorator
8563
909cf30c01c1 doc: rename input in examples to input_payload
John Rouillard <rouilj@ieee.org>
parents: 8543
diff changeset
2213 def generate_jwt(self, input_payload):
6519
22cf6ee7ad88 jwt issue example: require input data, lowercase roles
John Rouillard <rouilj@ieee.org>
parents: 6384
diff changeset
2214 """Create a JSON Web Token (jwt)
22cf6ee7ad88 jwt issue example: require input data, lowercase roles
John Rouillard <rouilj@ieee.org>
parents: 6384
diff changeset
2215 """
8022
f023b66c297d doc: update JWT example to use utcnow from anypy_datetime_
John Rouillard <rouilj@ieee.org>
parents: 7980
diff changeset
2216 import datetime
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2217 import jwt
8022
f023b66c297d doc: update JWT example to use utcnow from anypy_datetime_
John Rouillard <rouilj@ieee.org>
parents: 7980
diff changeset
2218 from roundup.anypy.datetime_ import utcnow
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2219 from roundup.anypy.strings import b2s
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2220
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2221 # require basic auth to generate a token
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2222 # At some point we can support a refresh token.
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2223 # maybe a jwt with the "refresh": True claim generated
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2224 # using: "refresh": True in the json request payload.
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2225
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2226 denialmsg='Token creation requires login with basic auth.'
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2227 if 'HTTP_AUTHORIZATION' in self.client.env:
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2228 try:
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2229 auth = self.client.env['HTTP_AUTHORIZATION']
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2230 scheme, challenge = auth.split(' ', 1)
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2231 except (ValueError, AttributeError):
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2232 # bad format for header
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2233 raise Unauthorised(denialmsg)
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2234 if scheme.lower() != 'basic':
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2235 raise Unauthorised(denialmsg)
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2236 else:
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2237 raise Unauthorised(denialmsg)
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2238
6519
22cf6ee7ad88 jwt issue example: require input data, lowercase roles
John Rouillard <rouilj@ieee.org>
parents: 6384
diff changeset
2239 # verify we have input data.
8563
909cf30c01c1 doc: rename input in examples to input_payload
John Rouillard <rouilj@ieee.org>
parents: 8543
diff changeset
2240 if not input_payload:
6519
22cf6ee7ad88 jwt issue example: require input data, lowercase roles
John Rouillard <rouilj@ieee.org>
parents: 6384
diff changeset
2241 raise UsageError("Missing data payload. "
22cf6ee7ad88 jwt issue example: require input data, lowercase roles
John Rouillard <rouilj@ieee.org>
parents: 6384
diff changeset
2242 "Verify Content-Type is sent")
22cf6ee7ad88 jwt issue example: require input data, lowercase roles
John Rouillard <rouilj@ieee.org>
parents: 6384
diff changeset
2243
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2244 # If we reach this point we have validated that the user has
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2245 # logged in with a password using basic auth.
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2246 all_roles = list(self.db.security.role.items())
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2247 rolenames = []
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2248 for role in all_roles:
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2249 rolenames.append(role[0])
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2250
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2251 user_roles = list(self.db.user.get_roles(self.db.getuid()))
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2252
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2253 claim= { 'sub': self.db.getuid(),
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2254 'iss': self.db.config.TRACKER_WEB,
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2255 'aud': self.db.config.TRACKER_WEB,
8022
f023b66c297d doc: update JWT example to use utcnow from anypy_datetime_
John Rouillard <rouilj@ieee.org>
parents: 7980
diff changeset
2256 'iat': utcnow(),
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2257 }
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2258
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2259 lifetime = 0
8563
909cf30c01c1 doc: rename input in examples to input_payload
John Rouillard <rouilj@ieee.org>
parents: 8543
diff changeset
2260 if 'lifetime' in input_payload:
909cf30c01c1 doc: rename input in examples to input_payload
John Rouillard <rouilj@ieee.org>
parents: 8543
diff changeset
2261 if input_payload['lifetime'].value != 'unlimited':
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2262 try:
8563
909cf30c01c1 doc: rename input in examples to input_payload
John Rouillard <rouilj@ieee.org>
parents: 8543
diff changeset
2263 lifetime = datetime.timedelta(seconds=int(input_payload['lifetime'].value))
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2264 except ValueError:
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2265 raise UsageError("Value 'lifetime' must be 'unlimited' or an integer to specify" +
8563
909cf30c01c1 doc: rename input in examples to input_payload
John Rouillard <rouilj@ieee.org>
parents: 8543
diff changeset
2266 " lifetime in seconds. Got %s."%input_payload['lifetime'].value)
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2267 else:
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2268 lifetime = datetime.timedelta(seconds=86400) # 1 day by default
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2269
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2270 if lifetime: # if lifetime = 0 make unlimited by omitting exp claim
8022
f023b66c297d doc: update JWT example to use utcnow from anypy_datetime_
John Rouillard <rouilj@ieee.org>
parents: 7980
diff changeset
2271 claim['exp'] = utcnow() + lifetime
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2272
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2273 newroles = []
8563
909cf30c01c1 doc: rename input in examples to input_payload
John Rouillard <rouilj@ieee.org>
parents: 8543
diff changeset
2274 if 'roles' in input_payload:
909cf30c01c1 doc: rename input in examples to input_payload
John Rouillard <rouilj@ieee.org>
parents: 8543
diff changeset
2275 for role in [ r.lower() for r in input_payload['roles'].value ]:
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2276 if role not in rolenames:
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2277 raise UsageError("Role %s is not valid."%role)
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2278 if role in user_roles:
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2279 newroles.append(role)
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2280 continue
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2281 parentrole = role.split(':', 1)[0]
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2282 if parentrole in user_roles:
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2283 newroles.append(role)
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2284 continue
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2285
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2286 raise UsageError("Role %s is not permitted."%role)
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2287
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2288 claim['roles'] = newroles
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2289 else:
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2290 claim['roles'] = user_roles
7809
be6cb2e0d471 feat: add support for rotating jwt keys
John Rouillard <rouilj@ieee.org>
parents: 7801
diff changeset
2291
be6cb2e0d471 feat: add support for rotating jwt keys
John Rouillard <rouilj@ieee.org>
parents: 7801
diff changeset
2292 # Sign with newest/first secret.
be6cb2e0d471 feat: add support for rotating jwt keys
John Rouillard <rouilj@ieee.org>
parents: 7801
diff changeset
2293 secret = self.db.config.WEB_JWT_SECRET[0]
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2294 myjwt = jwt.encode(claim, secret, algorithm='HS256')
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2295
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2296 # if jwt.__version__ >= 2.0.0 jwt.encode() returns string
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2297 # not byte. So do not use b2s() with newer versions of pyjwt.
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2298 result = {"jwt": b2s(myjwt),
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2299 }
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2300
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2301 return 200, result
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2302
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2303 @Routing.route("/jwt/validate", 'GET')
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2304 @_data_decorator
8563
909cf30c01c1 doc: rename input in examples to input_payload
John Rouillard <rouilj@ieee.org>
parents: 8543
diff changeset
2305 def validate_jwt(self,input_payload):
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2306 import jwt
8563
909cf30c01c1 doc: rename input in examples to input_payload
John Rouillard <rouilj@ieee.org>
parents: 8543
diff changeset
2307 if not 'jwt' in input_payload:
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2308 raise UsageError("jwt key must be specified")
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2309
8563
909cf30c01c1 doc: rename input in examples to input_payload
John Rouillard <rouilj@ieee.org>
parents: 8543
diff changeset
2310 myjwt = input_payload['jwt'].value
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2311
7809
be6cb2e0d471 feat: add support for rotating jwt keys
John Rouillard <rouilj@ieee.org>
parents: 7801
diff changeset
2312 secret = self.db.config.WEB_JWT_SECRET[0]
be6cb2e0d471 feat: add support for rotating jwt keys
John Rouillard <rouilj@ieee.org>
parents: 7801
diff changeset
2313
be6cb2e0d471 feat: add support for rotating jwt keys
John Rouillard <rouilj@ieee.org>
parents: 7801
diff changeset
2314 # only return decoded result if the newest signing key
be6cb2e0d471 feat: add support for rotating jwt keys
John Rouillard <rouilj@ieee.org>
parents: 7801
diff changeset
2315 # is used. Have older keys report an invalid signature.
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2316 try:
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2317 result = jwt.decode(myjwt, secret,
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2318 algorithms=['HS256'],
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2319 audience=self.db.config.TRACKER_WEB,
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2320 issuer=self.db.config.TRACKER_WEB,
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2321 )
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2322 except jwt.exceptions.InvalidTokenError as err:
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2323 return 401, str(err)
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2324
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
2325 return 200, result
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2326
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2327 **Note this is sample code. Use at your own risk.** It breaks a few
6764
32f52d14b496 Typo fixes, formatting fixes, jwt -> JWT, add link to JWT issue
John Rouillard <rouilj@ieee.org>
parents: 6681
diff changeset
2328 rules about JWTs (e.g. it allows you to make unlimited lifetime
32f52d14b496 Typo fixes, formatting fixes, jwt -> JWT, add link to JWT issue
John Rouillard <rouilj@ieee.org>
parents: 6681
diff changeset
2329 JWTs). If you subscribe to the concept of JWT refresh tokens, this code
32f52d14b496 Typo fixes, formatting fixes, jwt -> JWT, add link to JWT issue
John Rouillard <rouilj@ieee.org>
parents: 6681
diff changeset
2330 will have to be changed as it will only generate JWTs with
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2331 username/password authentication.
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2332
6764
32f52d14b496 Typo fixes, formatting fixes, jwt -> JWT, add link to JWT issue
John Rouillard <rouilj@ieee.org>
parents: 6681
diff changeset
2333 Currently use of JWTs an experiment. If this appeals to you consider
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2334 providing patches to existing code to:
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2335
7361
bc6bcffbed2a rewrite JWT future to use refresh tokens.
John Rouillard <rouilj@ieee.org>
parents: 7353
diff changeset
2336 1. create long lived refresh tokens
bc6bcffbed2a rewrite JWT future to use refresh tokens.
John Rouillard <rouilj@ieee.org>
parents: 7353
diff changeset
2337 2. record all refresh tokens created by a user
bc6bcffbed2a rewrite JWT future to use refresh tokens.
John Rouillard <rouilj@ieee.org>
parents: 7353
diff changeset
2338 3. using the record to allow refresh tokens to be revoked and
bc6bcffbed2a rewrite JWT future to use refresh tokens.
John Rouillard <rouilj@ieee.org>
parents: 7353
diff changeset
2339 ignored by the roundup core
bc6bcffbed2a rewrite JWT future to use refresh tokens.
John Rouillard <rouilj@ieee.org>
parents: 7353
diff changeset
2340 4. provide a UI page for managing/revoking refresh tokens
bc6bcffbed2a rewrite JWT future to use refresh tokens.
John Rouillard <rouilj@ieee.org>
parents: 7353
diff changeset
2341 5. provide a rest api for revoking refresh tokens
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2342
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2343 These end points can be used like::
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2344
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2345 curl -u demo -s -X POST -H "Referer: https://.../demo/" \
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2346 -H "X-requested-with: rest" \
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2347 -H "Content-Type: application/json" \
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2348 --data '{"lifetime": "3600", "roles": [ "user:timelog" ] }' \
6764
32f52d14b496 Typo fixes, formatting fixes, jwt -> JWT, add link to JWT issue
John Rouillard <rouilj@ieee.org>
parents: 6681
diff changeset
2349 https://.../demo/rest/JWT/issue
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2350
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2351 (note roles is a json array/list of strings not a string) to get::
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2352
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2353 {
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2354 "data": {
6764
32f52d14b496 Typo fixes, formatting fixes, jwt -> JWT, add link to JWT issue
John Rouillard <rouilj@ieee.org>
parents: 6681
diff changeset
2355 "JWT": "eyJ0eXAiOiJK......XxMDb-Q3oCnMpyhxPXMAk"
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2356 }
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2357 }
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2358
6764
32f52d14b496 Typo fixes, formatting fixes, jwt -> JWT, add link to JWT issue
John Rouillard <rouilj@ieee.org>
parents: 6681
diff changeset
2359 The JWT is shortened in the example since it's large. You can validate
32f52d14b496 Typo fixes, formatting fixes, jwt -> JWT, add link to JWT issue
John Rouillard <rouilj@ieee.org>
parents: 6681
diff changeset
2360 a JWT to see if it's still valid using::
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2361
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2362
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2363 curl -s -H "Referer: https://.../demo/" \
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2364 -H "X-requested-with: rest" \
6764
32f52d14b496 Typo fixes, formatting fixes, jwt -> JWT, add link to JWT issue
John Rouillard <rouilj@ieee.org>
parents: 6681
diff changeset
2365 https://.../demo/rest/JWT/validate?JWT=eyJ0eXAiOiJK...XxMDb-Q3oCnMpyhxPXMAk
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2366
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2367 (note no login is required) which returns::
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2368
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2369 {
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2370 "data": {
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2371 "user": "3",
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2372 "roles": [
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2373 "user:timelog"
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2374 ],
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2375 "iss": "https://.../demo/",
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2376 "aud": "https://.../demo/",
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2377 "iat": 1569542404,
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2378 "exp": 1569546004
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2379 }
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2380 }
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2381
6764
32f52d14b496 Typo fixes, formatting fixes, jwt -> JWT, add link to JWT issue
John Rouillard <rouilj@ieee.org>
parents: 6681
diff changeset
2382
32f52d14b496 Typo fixes, formatting fixes, jwt -> JWT, add link to JWT issue
John Rouillard <rouilj@ieee.org>
parents: 6681
diff changeset
2383 There is an issue for `thoughts on JWT credentials`_ that you can view
32f52d14b496 Typo fixes, formatting fixes, jwt -> JWT, add link to JWT issue
John Rouillard <rouilj@ieee.org>
parents: 6681
diff changeset
2384 for ideas or add your own.
32f52d14b496 Typo fixes, formatting fixes, jwt -> JWT, add link to JWT issue
John Rouillard <rouilj@ieee.org>
parents: 6681
diff changeset
2385
32f52d14b496 Typo fixes, formatting fixes, jwt -> JWT, add link to JWT issue
John Rouillard <rouilj@ieee.org>
parents: 6681
diff changeset
2386 .. _thoughts on JWT credentials: https://issues.roundup-tracker.org/issue2551064
32f52d14b496 Typo fixes, formatting fixes, jwt -> JWT, add link to JWT issue
John Rouillard <rouilj@ieee.org>
parents: 6681
diff changeset
2387
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2388 Final steps
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
2389 ~~~~~~~~~~~
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2390
5887
f4db6abf86d9 more typo fixes.
John Rouillard <rouilj@ieee.org>
parents: 5886
diff changeset
2391 See the `upgrading directions`_ on how to use the ``updateconfig``
5888
John Rouillard <rouilj@ieee.org>
parents: 5887
diff changeset
2392 command to generate an updated copy of config.ini using
6764
32f52d14b496 Typo fixes, formatting fixes, jwt -> JWT, add link to JWT issue
John Rouillard <rouilj@ieee.org>
parents: 6681
diff changeset
2393 roundup-admin. Then set the ``JWT_secret`` to at least 32 characters
7878
d4aef2b004a1 doc: ad use of openssl rand to generate jwt secret.
John Rouillard <rouilj@ieee.org>
parents: 7854
diff changeset
2394 (more is better up to 512 bits). The output of
d4aef2b004a1 doc: ad use of openssl rand to generate jwt secret.
John Rouillard <rouilj@ieee.org>
parents: 7854
diff changeset
2395 ``openssl rand -base64 32`` will fulfill the minimum requirements.
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2396
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2397 Writing an auditor that uses "db.user.get_roles" to see if the user
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2398 making the change has the ``user:timelog`` role, and then comparing
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2399 the original ``times`` list to the new list to verify that it is being
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2400 added to and not changed otherwise is left as an exercise for the
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2401 reader. (If you develop one, please contribute via the tracker:
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2402 https://issues.roundup-tracker.org/.)
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2403
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2404 Lastly you can create a JWT using the end point above and make a rest
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2405 call to create a new timelog entry and another call to update the
6764
32f52d14b496 Typo fixes, formatting fixes, jwt -> JWT, add link to JWT issue
John Rouillard <rouilj@ieee.org>
parents: 6681
diff changeset
2406 issues times property. If you have other ideas on how JWTs can be
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2407 used, please share on the roundup mailing lists. See:
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2408 https://sourceforge.net/p/roundup/mailman/ for directions on
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2409 subscribing and for archives of the lists.
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2410
5843
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
2411
5737
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2412 Creating Custom Rate Limits
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
2413 ---------------------------
5737
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2414
5738
9777d7311bc0 Clean up the custom rate limit doc.
John Rouillard <rouilj@ieee.org>
parents: 5737
diff changeset
2415 You can replace the default rate limiter that is configured using
9777d7311bc0 Clean up the custom rate limit doc.
John Rouillard <rouilj@ieee.org>
parents: 5737
diff changeset
2416 the tracker's ``config.ini``. You can return different rate
6674
ff8845ca305e issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents: 6630
diff changeset
2417 limits based on the user, time of day, phase of moon, request
ff8845ca305e issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents: 6630
diff changeset
2418 method (via self.client.request.command) etc.
5738
9777d7311bc0 Clean up the custom rate limit doc.
John Rouillard <rouilj@ieee.org>
parents: 5737
diff changeset
2419
9777d7311bc0 Clean up the custom rate limit doc.
John Rouillard <rouilj@ieee.org>
parents: 5737
diff changeset
2420 Assume you add two integer valued properties to the user
9777d7311bc0 Clean up the custom rate limit doc.
John Rouillard <rouilj@ieee.org>
parents: 5737
diff changeset
2421 object. Let's call them ``rate_limit_interval`` and
9777d7311bc0 Clean up the custom rate limit doc.
John Rouillard <rouilj@ieee.org>
parents: 5737
diff changeset
2422 ``rate_limit_calls``. Add code similar to this to interfaces.py
9777d7311bc0 Clean up the custom rate limit doc.
John Rouillard <rouilj@ieee.org>
parents: 5737
diff changeset
2423 to override the default rate limiter code::
5737
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2424
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2425 from roundup.rest import RestfulInstance, RateLimit
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2426 from datetime import timedelta
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2427
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2428 def grl(self):
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2429 calls = self.db.config.WEB_API_CALLS_PER_INTERVAL
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2430 interval = self.db.config.WEB_API_INTERVAL_IN_SEC
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2431
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2432 if calls and interval: # use to disable all rate limits
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2433
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2434 uid = self.db.getuid()
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2435 class_obj = self.db.getclass('user')
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2436 node = class_obj.getnode(uid)
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2437
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2438 # set value to 0 to use WEB_API_CALLS_PER_INTERVAL
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2439 user_calls = node.__getattr__('rate_limit_calls')
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2440 # set to 0 to use WEB_API_INTERVAL_IN_SEC
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2441 user_interval = node.__getattr__('rate_limit_interval')
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2442
5737
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2443 return RateLimit(user_calls or calls,
7801
af898d1d66dc doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents: 7733
diff changeset
2444 timedelta(seconds=(user_interval or interval)))
5737
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2445 else:
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2446 # disable rate limiting if either parameter is 0
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2447 return None
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2448
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2449 RestfulInstance.getRateLimit = grl
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2450
5738
9777d7311bc0 Clean up the custom rate limit doc.
John Rouillard <rouilj@ieee.org>
parents: 5737
diff changeset
2451 this should replace the default getRateLimit with the new grl
9777d7311bc0 Clean up the custom rate limit doc.
John Rouillard <rouilj@ieee.org>
parents: 5737
diff changeset
2452 function. This new function uses values for the number of calls
9777d7311bc0 Clean up the custom rate limit doc.
John Rouillard <rouilj@ieee.org>
parents: 5737
diff changeset
2453 and period that are specific to a user. If either is set to 0,
9777d7311bc0 Clean up the custom rate limit doc.
John Rouillard <rouilj@ieee.org>
parents: 5737
diff changeset
2454 the defaults from ``config.ini`` file are used.
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
2455
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
2456 Test Examples
7473
f8b5b0310f88 I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents: 7455
diff changeset
2457 ~~~~~~~~~~~~~
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
2458
5895
93bbe5340d5b More typo fixes and verbatim blocks.
John Rouillard <rouilj@ieee.org>
parents: 5894
diff changeset
2459 Rate limit tests::
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
2460
6765
b4bfbd768bc1 How to add dicttoxml at system or tracker level.
John Rouillard <rouilj@ieee.org>
parents: 6764
diff changeset
2461 seq 1 300 | xargs -P 20 -n 1 curl --head -u user:password -si \
b4bfbd768bc1 How to add dicttoxml at system or tracker level.
John Rouillard <rouilj@ieee.org>
parents: 6764
diff changeset
2462 https://.../rest/data/status/new | grep Remaining
b4bfbd768bc1 How to add dicttoxml at system or tracker level.
John Rouillard <rouilj@ieee.org>
parents: 6764
diff changeset
2463
b4bfbd768bc1 How to add dicttoxml at system or tracker level.
John Rouillard <rouilj@ieee.org>
parents: 6764
diff changeset
2464 will show you the number of remaining requests to the REST interface
b4bfbd768bc1 How to add dicttoxml at system or tracker level.
John Rouillard <rouilj@ieee.org>
parents: 6764
diff changeset
2465 for the user identified by password.
8218
32aaf5dc562b fix(REST): issue2551383; improve errors for bad json, fix PUT docs
John Rouillard <rouilj@ieee.org>
parents: 8212
diff changeset
2466
32aaf5dc562b fix(REST): issue2551383; improve errors for bad json, fix PUT docs
John Rouillard <rouilj@ieee.org>
parents: 8212
diff changeset
2467
32aaf5dc562b fix(REST): issue2551383; improve errors for bad json, fix PUT docs
John Rouillard <rouilj@ieee.org>
parents: 8212
diff changeset
2468 Notes V2 API
32aaf5dc562b fix(REST): issue2551383; improve errors for bad json, fix PUT docs
John Rouillard <rouilj@ieee.org>
parents: 8212
diff changeset
2469 ~~~~~~~~~~~~
32aaf5dc562b fix(REST): issue2551383; improve errors for bad json, fix PUT docs
John Rouillard <rouilj@ieee.org>
parents: 8212
diff changeset
2470
32aaf5dc562b fix(REST): issue2551383; improve errors for bad json, fix PUT docs
John Rouillard <rouilj@ieee.org>
parents: 8212
diff changeset
2471 These may never be implemented but, some nits to consider.
32aaf5dc562b fix(REST): issue2551383; improve errors for bad json, fix PUT docs
John Rouillard <rouilj@ieee.org>
parents: 8212
diff changeset
2472
32aaf5dc562b fix(REST): issue2551383; improve errors for bad json, fix PUT docs
John Rouillard <rouilj@ieee.org>
parents: 8212
diff changeset
2473 The shape of a GET and PUT/PATCH responses are different. "attributes"
32aaf5dc562b fix(REST): issue2551383; improve errors for bad json, fix PUT docs
John Rouillard <rouilj@ieee.org>
parents: 8212
diff changeset
2474 is used for GET and "attribute" is used with PATCH/PUT. A PATCH or a
32aaf5dc562b fix(REST): issue2551383; improve errors for bad json, fix PUT docs
John Rouillard <rouilj@ieee.org>
parents: 8212
diff changeset
2475 PUT can update multiple properties when used with an item endpoint.
32aaf5dc562b fix(REST): issue2551383; improve errors for bad json, fix PUT docs
John Rouillard <rouilj@ieee.org>
parents: 8212
diff changeset
2476 "attribute" kind of makes sense when used with a property endpoint
32aaf5dc562b fix(REST): issue2551383; improve errors for bad json, fix PUT docs
John Rouillard <rouilj@ieee.org>
parents: 8212
diff changeset
2477 but.... Maybe standardize on one shape so the client doesn't have to
32aaf5dc562b fix(REST): issue2551383; improve errors for bad json, fix PUT docs
John Rouillard <rouilj@ieee.org>
parents: 8212
diff changeset
2478 special case?
Roundup Issue Tracker: http://roundup-tracker.org/