Mercurial > p > roundup > code
annotate doc/rest.txt @ 8180:d02ce1d14acd
feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
Use Allow header to change format of /binary_content endpoint. If
Allow header for endpoint is not application/json, it will be matched
against the mime type for the file. */*, text/* are supported and will
return the native mime type if present.
Changes:
move */* mime type from static dict of supported types. It was
hardcoded to return json only. Now it can return a matching
non-json mime type for the /binary_content endpoint.
Edited some errors to explicitly add */* mime type.
Cleanups to use ', ' separation in lists of valid mime types rather
than just space separated.
Remove ETag header when sending raw content. See issue 2551375 for
background.
Doc added to rest.txt.
Small format fix up (add dash) in CHANGES.txt.
Make passing an unset/None/False accept_mime_type to
format_dispatch_output a 500 error. This used to be the fallback
to produce a 406 error after all processing had happened. It
should no longer be possible to take that code path as all 406
errors (with valid accept_mime_types) are generated before
processing takes place.
Make format_dispatch_output handle output other than json/xml so it
can send back binary_content data.
Removed a spurious client.response_code = 400 that seems to not be
used.
Tests added for all code paths.
Database setup for tests msg and file entry. This required a file
upload test to change so it doesn't look for file1 as the link
returned by the upload. Download the link and verify the data
rather than verifying the link.
Multiple formatting changes to error messages to make all lists of
valid mime types ', ' an not just space separated.
| author | John Rouillard <rouilj@ieee.org> |
|---|---|
| date | Sun, 08 Dec 2024 17:22:33 -0500 |
| parents | bd628e64725f |
| children | 79b9343794f5 |
| 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 | 7 .. index:: pair: api; Representational state transfer |
| 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 | 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 |
|
7684
3eca3462ba0c
fix: add support for dicttoxml2.py
John Rouillard <rouilj@ieee.org>
parents:
7636
diff
changeset
|
378 Note: ``dicttoxml2.py`` is an updated version of ``dicttoxml.py``. If |
|
7685
0e3d31a6b7fd
doc: clarify use of .xml or .json extensions in REST interface
John Rouillard <rouilj@ieee.org>
parents:
7684
diff
changeset
|
379 you are still using Python 2.7 or 3.6, you can use ``dicttoxml.py``. |
|
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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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, |
|
d02ce1d14acd
feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents:
8175
diff
changeset
|
948 you can use ``image/png`` or ``*/*`` in the Accept header. |
|
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; |
|
d02ce1d14acd
feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents:
8175
diff
changeset
|
953 q=0.495, text/*``. It will return the plain text of the message. |
|
d02ce1d14acd
feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents:
8175
diff
changeset
|
954 |
|
d02ce1d14acd
feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents:
8175
diff
changeset
|
955 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
|
956 ``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
|
957 |
|
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 "data": { |
|
d02ce1d14acd
feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents:
8175
diff
changeset
|
960 "id": "23", |
|
d02ce1d14acd
feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents:
8175
diff
changeset
|
961 "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
|
962 "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
|
963 "data": null, |
|
d02ce1d14acd
feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents:
8175
diff
changeset
|
964 "@etag": "\"ba98927a8bb4c56f6cfc31a36f94ad16\"" |
|
d02ce1d14acd
feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents:
8175
diff
changeset
|
965 } |
|
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 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
|
969 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
|
970 |
|
d02ce1d14acd
feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents:
8175
diff
changeset
|
971 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
|
972 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
|
973 ``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
|
974 mime type. If the item's type is not empty, it will be used as the |
|
d02ce1d14acd
feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents:
8175
diff
changeset
|
975 Content-Type (similar to ``*/*``). Otherwise ``text/*`` will be the |
|
d02ce1d14acd
feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents:
8175
diff
changeset
|
976 Content-Type. If your tracker supports markup languages |
|
d02ce1d14acd
feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents:
8175
diff
changeset
|
977 (e.g. markdown), you should set the mime type (e.g. ``text/markdown``) |
|
d02ce1d14acd
feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents:
8175
diff
changeset
|
978 when storing your message. |
|
d02ce1d14acd
feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents:
8175
diff
changeset
|
979 |
|
d02ce1d14acd
feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents:
8175
diff
changeset
|
980 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
|
981 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
|
982 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
|
983 |
|
d02ce1d14acd
feat: issue2551068 - Provide way to retrieve file/msg data via rest endpoint.
John Rouillard <rouilj@ieee.org>
parents:
8175
diff
changeset
|
984 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
|
985 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
|
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 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
|
988 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
|
989 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
|
990 |
|
5928
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
991 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
|
992 ``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
|
993 /, 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
|
994 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
|
995 |
|
6630
0351caa802f7
Add missing url in example.
John Rouillard <rouilj@ieee.org>
parents:
6586
diff
changeset
|
996 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
|
997 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
|
998 like:: |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
999 |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1000 ... |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1001 "author": { |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1002 "id": "5", |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1003 "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
|
1004 }, |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1005 "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
|
1006 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
|
1007 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
|
1008 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
|
1009 "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
|
1010 ... |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1011 |
|
5928
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1012 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
|
1013 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
|
1014 |
|
5929
0368d75de544
issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents:
5928
diff
changeset
|
1015 Retrieving the contents of a file is similar. Performing a |
|
0368d75de544
issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents:
5928
diff
changeset
|
1016 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
|
1017 |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1018 { |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1019 "data": { |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1020 "id": "11", |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1021 "type": "file", |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1022 "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
|
1023 "attributes": { |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1024 "acl": null, |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1025 "content": { |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1026 "link": "https://.../demo/file11/" |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1027 }, |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1028 "name": "afile", |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1029 "status": { |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1030 "id": "1", |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1031 "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
|
1032 }, |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1033 "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
|
1034 }, |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1035 "@etag": "\"74276f75ef71a30a0cce62dc6a8aa1bb\"" |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1036 } |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1037 } |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1038 |
|
5929
0368d75de544
issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents:
5928
diff
changeset
|
1039 To download the file contents for this example you would |
|
0368d75de544
issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents:
5928
diff
changeset
|
1040 perform an http GET using: ``https://.../demo/file11/``. The trailing |
|
0368d75de544
issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents:
5928
diff
changeset
|
1041 / 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
|
1042 application/octet-stream. |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1043 |
|
5929
0368d75de544
issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents:
5928
diff
changeset
|
1044 If you perform a get on |
|
0368d75de544
issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents:
5928
diff
changeset
|
1045 ``https://.../demo/rest/data/file/11?@verbose=3`` the content field |
|
0368d75de544
issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents:
5928
diff
changeset
|
1046 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
|
1047 |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1048 "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
|
1049 property. mdsum: bd990c0f8833dd991daf610b81b62316", |
|
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 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
|
1052 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
|
1053 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1054 Other query params |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
1055 ~~~~~~~~~~~~~~~~~~ |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1056 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1057 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
|
1058 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1059 .. list-table:: Query Parameters Examples |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1060 :header-rows: 1 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1061 :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
|
1062 :class: valign-top |
|
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 * - Query parameter |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1065 - Explanation |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1066 * - ``@pretty=false`` |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1067 - 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
|
1068 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
|
1069 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
|
1070 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
|
1071 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
|
1072 this time. |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1073 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1074 Using the POST method |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
1075 ~~~~~~~~~~~~~~~~~~~~~ |
|
5660
d8d2b7724292
First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff
changeset
|
1076 |
|
d8d2b7724292
First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff
changeset
|
1077 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
|
1078 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
|
1079 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
|
1080 parameters as the GET method after successful creation. |
|
d8d2b7724292
First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff
changeset
|
1081 |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1082 If you perform a get on an item with ``@verbose=0``, it is in the |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1083 correct form to use as a the payload of a post. |
|
5660
d8d2b7724292
First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff
changeset
|
1084 |
|
d8d2b7724292
First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff
changeset
|
1085 |
|
5710
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1086 Safely Re-sending POST |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1087 ^^^^^^^^^^^^^^^^^^^^^^ |
|
5710
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1088 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1089 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
|
1090 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
|
1091 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
|
1092 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
|
1093 |
|
5710
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1094 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
|
1095 Once Exactly spec: |
| 7139 | 1096 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
|
1097 |
|
5710
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1098 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
|
1099 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
|
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 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
|
1102 |
|
5710
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1103 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
|
1104 -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
|
1105 -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
|
1106 --data '' \ |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1107 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
|
1108 |
|
5710
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1109 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
|
1110 |
|
5710
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1111 { |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1112 "data": { |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1113 "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
|
1114 "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
|
1115 } |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1116 } |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1117 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1118 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
|
1119 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
|
1120 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
|
1121 |
|
5710
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1122 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
|
1123 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
|
1124 ``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
|
1125 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1126 For example:: |
|
5688
1b9ef04b9528
Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents:
5678
diff
changeset
|
1127 |
|
5710
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1128 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
|
1129 -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
|
1130 -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
|
1131 -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
|
1132 --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
|
1133 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
|
1134 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1135 returns:: |
|
5688
1b9ef04b9528
Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents:
5678
diff
changeset
|
1136 |
|
5710
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1137 { |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1138 "data": { |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1139 "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
|
1140 "id": "2280" |
|
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 } |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1143 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1144 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
|
1145 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
|
1146 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
|
1147 |
|
6261
424f70c076b9
Grammar fix. Remove word missed in rewrite.
John Rouillard <rouilj@ieee.org>
parents:
6207
diff
changeset
|
1148 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
|
1149 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
|
1150 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
|
1151 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
|
1152 |
|
5710
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1153 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
|
1154 -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
|
1155 --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
|
1156 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
|
1157 |
|
5710
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1158 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
|
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 { |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1161 "data": { |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1162 "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
|
1163 "link": |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1164 "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
|
1165 } |
|
5710
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1166 } |
|
5688
1b9ef04b9528
Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents:
5678
diff
changeset
|
1167 |
|
5710
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1168 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
|
1169 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
|
1170 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
|
1171 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1172 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
|
1173 a lifetime of 15 minutes (900 seconds). Using it after 16 minutes will |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1174 result in a 400 error. A lifetime up to 1 hour can be specified. |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1175 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1176 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
|
1177 |
|
5710
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1178 * 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
|
1179 * 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
|
1180 * 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
|
1181 fails |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1182 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1183 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
|
1184 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
|
1185 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
|
1186 mechanism. |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1187 |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1188 .. [#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
|
1189 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
|
1190 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
|
1191 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
|
1192 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
|
1193 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
|
1194 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
|
1195 response was lost. |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1196 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1197 Other Supported Methods for Collections |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
1198 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1199 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1200 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
|
1201 allowed on a given endpoint. |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1202 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1203 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
|
1204 |
|
7972
425dd9854e34
feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents:
7878
diff
changeset
|
1205 /data/user/roles endpoint |
|
425dd9854e34
feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents:
7878
diff
changeset
|
1206 ------------------------- |
|
425dd9854e34
feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents:
7878
diff
changeset
|
1207 |
|
425dd9854e34
feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents:
7878
diff
changeset
|
1208 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
|
1209 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
|
1210 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
|
1211 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
|
1212 |
|
425dd9854e34
feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents:
7878
diff
changeset
|
1213 { |
|
425dd9854e34
feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents:
7878
diff
changeset
|
1214 "data": { |
|
425dd9854e34
feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents:
7878
diff
changeset
|
1215 "collection": [ |
|
425dd9854e34
feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents:
7878
diff
changeset
|
1216 { |
|
425dd9854e34
feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents:
7878
diff
changeset
|
1217 "id": "user", |
|
425dd9854e34
feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents:
7878
diff
changeset
|
1218 "name": "user" |
|
425dd9854e34
feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents:
7878
diff
changeset
|
1219 }, |
|
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 "id": "admin", |
|
425dd9854e34
feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents:
7878
diff
changeset
|
1222 "name": "admin" |
|
425dd9854e34
feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents:
7878
diff
changeset
|
1223 }, |
|
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": "anonymous", |
|
425dd9854e34
feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents:
7878
diff
changeset
|
1226 "name": "anonymous" |
|
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 } |
|
425dd9854e34
feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents:
7878
diff
changeset
|
1230 } |
|
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 to mimic a class collection. |
|
425dd9854e34
feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents:
7878
diff
changeset
|
1233 |
|
425dd9854e34
feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents:
7878
diff
changeset
|
1234 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
|
1235 returned. Also it does not support and ignores any query options like: |
| 7980 | 1236 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
|
1237 property is not numeric. |
|
7972
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 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
|
1240 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
|
1241 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
|
1242 classhelper. |
|
425dd9854e34
feat: document the /rest/data/user/roles endpoint
John Rouillard <rouilj@ieee.org>
parents:
7878
diff
changeset
|
1243 |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1244 /data/\ *class*/\ *id* item |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
1245 --------------------------- |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1246 |
|
7853
03c1b7ae3a68
issue2551328/issue2551264 unneeded next link and total_count incorrect
John Rouillard <rouilj@ieee.org>
parents:
7825
diff
changeset
|
1247 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
|
1248 (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
|
1249 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
|
1250 (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
|
1251 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
|
1252 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1253 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
|
1254 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
|
1255 account used for the query. |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1256 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1257 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
|
1258 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
|
1259 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
|
1260 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
|
1261 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
|
1262 transitive properties. By default protected |
|
5892
afb5705d1fe5
Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
5888
diff
changeset
|
1263 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
|
1264 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
|
1265 ``@verbose=0`` query using PUT. To include protected properties |
| 5854 | 1266 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
|
1267 ``@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
|
1268 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
|
1269 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1270 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
|
1271 ``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
|
1272 ``@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
|
1273 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
|
1274 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
|
1275 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
|
1276 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
|
1277 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
|
1278 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
|
1279 @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
|
1280 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
|
1281 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
|
1282 currently discouraged. |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1283 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1284 An example of returned values:: |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1285 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1286 { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1287 "data": { |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1288 "type": "issue", |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1289 "@etag": "\"f15e6942f00a41960de45f9413684591\"", |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1290 "link": "https://.../rest/data/issue/23", |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1291 "attributes": { |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1292 "keyword": [], |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1293 "messages": [ |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1294 { |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1295 "link": "https://.../rest/data/msg/375", |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1296 "id": "375" |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1297 }, |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1298 { |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1299 "link": "https://.../rest/data/msg/376", |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1300 "id": "376" |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1301 }, |
|
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 ], |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1304 "files": [], |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1305 "status": { |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1306 "link": "https://.../rest/data/status/2", |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1307 "id": "2" |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1308 }, |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1309 "title": "This is a title title", |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1310 "superseder": [], |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1311 "nosy": [ |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1312 { |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1313 "link": "https://.../rest/data/user/4", |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1314 "id": "4" |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1315 }, |
|
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 "link": "https://.../rest/data/user/5", |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1318 "id": "5" |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1319 } |
|
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 "assignedto": null, |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1322 }, |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1323 "id": "23" |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1324 } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1325 } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1326 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1327 Retrieve item using key value |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
1328 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1329 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1330 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
|
1331 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
|
1332 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1333 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
|
1334 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
|
1335 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
|
1336 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
|
1337 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
|
1338 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
|
1339 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
|
1340 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
|
1341 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
|
1342 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1343 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
|
1344 ``/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
|
1345 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
|
1346 |
|
5928
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1347 Dealing with Messages and Files |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
1348 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
5928
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1349 |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1350 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
|
1351 |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1352 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
|
1353 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
|
1354 |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1355 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
|
1356 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
|
1357 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
|
1358 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
|
1359 |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1360 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
|
1361 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
|
1362 parameters, e.g.:: |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1363 |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1364 # 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
|
1365 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
|
1366 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
|
1367 fname = 'a-bigger-testfile' |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1368 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
|
1369 c = dict (content = content) |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1370 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
|
1371 |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1372 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
|
1373 |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1374 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
|
1375 -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
|
1376 -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
|
1377 -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
|
1378 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
|
1379 |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1380 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
|
1381 return something like:: |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1382 |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1383 { |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1384 "data": { |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1385 "id": "12", |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1386 "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
|
1387 } |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1388 } |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1389 |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1390 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1391 Other Supported Methods for Items |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
1392 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1393 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1394 The method ``PUT`` is allowed on individual items, e.g. |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1395 ``/data/issue/42`` On success it returns the same parameters as the |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1396 respective ``GET`` method. Note that for ``PUT`` an Etag has to be |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1397 supplied, either in the request header or as an @etag parameter. An |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1398 example:: |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1399 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1400 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
|
1401 --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
|
1402 --header 'X-Requested-With: rest' \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1403 --header "Content-Type: application/json" \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1404 --header "Accept: application/json" \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1405 --header 'If-Match: "dd41f02d6f8b4c34b439fc712b522fb3"' \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1406 --data '{ "nosy": [ "1", "5" ] }' \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1407 "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
|
1408 |
|
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 "data": { |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1411 "attribute": { |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1412 "nosy": [ |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1413 "1", |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1414 "5" |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1415 ] |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1416 }, |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1417 "type": "issue", |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1418 "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
|
1419 "id": "23" |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1420 } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1421 } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1422 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1423 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
|
1424 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1425 --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
|
1426 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1427 this is returned:: |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1428 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1429 { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1430 "data": { |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1431 "attribute": { |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1432 "title": "This is now my title" |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1433 }, |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1434 "type": "issue", |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1435 "link": |
|
5928
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1436 "https://.../demo/rest/data/issue/23", |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1437 "id": "23" |
|
5723
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 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1441 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
|
1442 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
|
1443 Changing both nosy and title:: |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1444 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1445 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
|
1446 --header 'Referer: https://.../' \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1447 --header 'X-Requested-With: rest' \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1448 --header "Content-Type: application/json" \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1449 --header "Accept: application/json" \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1450 --header 'If-Match: "8209add59a79713d64f4d1a072aef740"' \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1451 --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
|
1452 "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
|
1453 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1454 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
|
1455 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1456 { |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1457 "data": { |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1458 "attribute": { |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1459 "title": "This is now my new title", |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1460 "nosy": [ |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1461 "4", |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1462 "5" |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1463 ] |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1464 }, |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1465 "type": "issue", |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1466 "link": |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1467 "https://.../demo/rest/data/issue/23", |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1468 "id": "23" |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1469 } |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1470 } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1471 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1472 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
|
1473 work. So using:: |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1474 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1475 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
|
1476 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1477 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
|
1478 payload:: |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1479 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1480 curl -u admin:admin ... |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1481 --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
|
1482 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1483 produces:: |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1484 |
|
5892
afb5705d1fe5
Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
5888
diff
changeset
|
1485 {"data": {"attribute": {...}, "type": "issue", |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1486 "link": "https://...", "id": "23"}} |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1487 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1488 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
|
1489 line. |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1490 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1491 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
|
1492 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
|
1493 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
|
1494 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
|
1495 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
|
1496 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1497 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
|
1498 ``/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
|
1499 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
|
1500 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
|
1501 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
|
1502 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
|
1503 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
|
1504 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
|
1505 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
|
1506 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
|
1507 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
|
1508 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
|
1509 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
|
1510 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1511 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
|
1512 --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
|
1513 --header "Accept: application/json" \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1514 --header 'If-Match: "c6e2d81019acff1da7a2da45f93939bd"' \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1515 --data-urlencode '@op=add' \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1516 --data 'nosy=3' \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1517 "https://.../rest/data/issue/23" |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1518 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1519 which returns:: |
|
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 { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1522 "data": { |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1523 "attribute": { |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1524 "nosy": [ |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1525 "3", |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1526 "4" |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1527 ] |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1528 }, |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1529 "type": "issue", |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1530 "link": "https://.../rest/data/issue/23", |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1531 "id": "23" |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1532 } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1533 } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1534 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1535 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
|
1536 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
|
1537 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1538 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
|
1539 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
|
1540 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
|
1541 ``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
|
1542 ``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
|
1543 ``@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
|
1544 ``If-Match`` header. |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1545 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1546 /data/\ *class*/\ *id*/\ *property* field |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
1547 ----------------------------------------- |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1548 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1549 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
|
1550 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
|
1551 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
|
1552 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1553 For example:: |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1554 |
|
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": { |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1557 "link": "https://.../rest/data/issue/22/title", |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1558 "data": "I need Broken PC", |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1559 "type": "<class 'str'>", |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1560 "id": "22", |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1561 "@etag": "\"370510512b2d8fc3f98aac3d762cc7b1\"" |
|
5723
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 } |
|
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 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
|
1567 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
|
1568 |
|
5928
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1569 Message and File Content |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
1570 ~~~~~~~~~~~~~~~~~~~~~~~~ |
|
5928
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1571 |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1572 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
|
1573 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
|
1574 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
|
1575 |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1576 { |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1577 "data": { |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1578 "id": "11", |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1579 "type": "<class 'str'>", |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1580 "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
|
1581 "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
|
1582 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
|
1583 "@etag": "\"584f82231079e349031bbb853747df1c\"" |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1584 } |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1585 } |
|
5928
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 (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
|
1588 |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1589 .. _binary_content property: |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1590 |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1591 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
|
1592 binary_content |
|
5930
cc6891ea1f01
issue2551067 make url into liternal not clickble.
John Rouillard <rouilj@ieee.org>
parents:
5929
diff
changeset
|
1593 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
|
1594 returns:: |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1595 |
|
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 "data": { |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1598 "id": "11", |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1599 "type": "<class 'bytes'>", |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1600 "link": "https://.../demo/rest/data/file/11/binary_content", |
|
5929
0368d75de544
issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents:
5928
diff
changeset
|
1601 "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
|
1602 "@etag": "\"74276f75ef71a30a0cce62dc6a8aa1bb\"" |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1603 } |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1604 } |
|
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 (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
|
1607 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
|
1608 Content`_. |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1609 |
|
5929
0368d75de544
issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents:
5928
diff
changeset
|
1610 The data is a json encoded hexidecimal representation of the data. |
|
0368d75de544
issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents:
5928
diff
changeset
|
1611 |
|
5928
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1612 |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1613 Other Supported Methods for fields |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
1614 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1615 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1616 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
|
1617 ``/data/issue/42/title``. On success it returns the same parameters as |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1618 the respective ``GET`` method. Note that for ``PUT`` an Etag has to be |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1619 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
|
1620 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
|
1621 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1622 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
|
1623 --header "Accept: application/json" \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1624 --data "data=Provisional" \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1625 --header "If-Match: 079eba599152f3eed00567e23258fecf" \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1626 --data-urlencode "@etag=079eba599152f3eed00567e23258fecf" \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1627 "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
|
1628 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1629 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
|
1630 type:: |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1631 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1632 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
|
1633 --header "Accept: application/json" \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1634 --header 'Content-Type: application/json' \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1635 --header "Referer: https://.../" \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1636 --header "x-requested-with: rest" \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1637 --header 'If-Match: "e2e6cc43c3475a4a3d9e5343617c11c3"' \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1638 --data '{"leadtime": "2d" }' \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1639 "https://.../rest/data/issue/10" |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1640 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1641 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
|
1642 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
|
1643 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
|
1644 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
|
1645 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1646 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
|
1647 ``/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
|
1648 ``@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
|
1649 ``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
|
1650 which is the same as performing a PUT on the field url. ``add`` and |
| 5854 | 1651 ``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
|
1652 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
|
1653 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
|
1654 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
|
1655 method. |
|
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 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
|
1658 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
|
1659 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
|
1660 ``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
|
1661 ``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
|
1662 ``@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
|
1663 ``If-Match`` header. |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1664 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1665 Tunneling Methods via POST |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
1666 -------------------------- |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1667 |
| 7455 | 1668 If you are working through a proxy and unable to use http methods like |
| 1669 PUT, PATCH, or DELETE, you can use POST to perform the action. To tunnel | |
| 5854 | 1670 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
|
1671 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
|
1672 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
|
1673 without tunneling. |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1674 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1675 Examples and Use Cases |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
1676 ====================== |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1677 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1678 sample python client |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
1679 -------------------- |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1680 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1681 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
|
1682 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
|
1683 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1684 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1685 >>> import requests |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1686 >>> 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
|
1687 >>> s = requests.session() |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1688 >>> session.auth = ('admin', 'admin') |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1689 >>> 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
|
1690 >>> if r.status_code != 200: |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1691 ... 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
|
1692 ... exit(1) |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1693 >>> print (r.json() ['data']['data'] |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1694 TEST Title |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1695 >>> 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
|
1696 >>> 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
|
1697 >>> 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
|
1698 ... 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
|
1699 ... exit(1) |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1700 >>> print(r.json()) |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1701 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1702 Retire/Restore:: |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1703 >>> 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
|
1704 >>> print (r.json()) |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1705 >>> 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
|
1706 >>> etag = r.headers['ETag'] |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1707 >>> print("ETag: %s" % etag) |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1708 >>> etag = r.json()['data']['@etag'] |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1709 >>> print("@etag: %s" % etag) |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1710 >>> h = {'If-Match': etag, |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1711 ... 'X-Requested-With': 'rest', |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1712 ... '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
|
1713 >>> 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
|
1714 >>> 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
|
1715 >>> print(r.json()) |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1716 >>> 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
|
1717 >>> 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
|
1718 >>> print(r.json()) |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1719 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1720 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
|
1721 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
|
1722 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
|
1723 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
|
1724 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
|
1725 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
|
1726 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
|
1727 |
| 6204 | 1728 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
|
1729 |
|
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1730 curl -s -u admin:admin \ |
|
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1731 -H "Referer: https://tracker.example.com/demo/" \ |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1732 -H "X-requested-with: rest" \ |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1733 -H "Content-Type: application/json" \ |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1734 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
|
1735 |
|
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1736 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
|
1737 for this retire example:: |
|
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1738 |
|
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1739 curl -s -u admin:admin \ |
|
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1740 -H "Referer: https://tracker.example.com/demo/" \ |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1741 -H "X-requested-with: rest" \ |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1742 -H "Content-Type: application/json" \ |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1743 -H 'If-Match: "a502faf4d6b8e3897c4ecd66b5597571"' \ |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1744 --data-raw '{ "@op":"action", "@action_name": "retire" }'\ |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1745 -X PATCH \ |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1746 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
|
1747 |
|
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1748 and restore:: |
|
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1749 |
|
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1750 curl -s -u admin:admin \ |
|
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1751 -H "Referer: https://tracker.example.com/demo/" \ |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1752 -H "X-requested-with: rest" \ |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1753 -H "Content-Type: application/json" \ |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1754 -H 'If-Match: "a502faf4d6b8e3897c4ecd66b5597571"' \ |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1755 --data-raw '{ "@op":"action", "@action_name": "restore" }'\ |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1756 -X PATCH \ |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1757 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
|
1758 |
|
5695
3e1b66c4e1e2
Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents:
5688
diff
changeset
|
1759 |
|
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
|
1760 Searches and selection |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
1761 ---------------------- |
|
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
|
1762 |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
1763 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
|
1764 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
|
1765 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
|
1766 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
|
1767 |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
1768 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
|
1769 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
|
1770 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
|
1771 |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
1772 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
|
1773 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
|
1774 |
|
5695
3e1b66c4e1e2
Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents:
5688
diff
changeset
|
1775 $('#superseder').selectize({ |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1776 valueField: 'id', |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1777 labelField: 'title', |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1778 searchField: 'title', ... |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1779 load: function(query, callback) { |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1780 if (!query.length) return callback(); |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1781 $.ajax({ |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1782 url: '.../rest/data/issue?@verbose=2&title=' |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1783 + encodeURIComponent(query), |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1784 type: 'GET', |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1785 error: function() {callback();}, |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1786 success: function(res) { |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1787 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
|
1788 |
|
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 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
|
1790 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
|
1791 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
|
1792 |
|
5695
3e1b66c4e1e2
Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents:
5688
diff
changeset
|
1793 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
|
1794 |
|
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 { |
|
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 "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
|
1797 "@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
|
1798 "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
|
1799 { |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1800 "link": ".../rest/data/issue/8", |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1801 "id": "8", |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1802 "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
|
1803 }, |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
1804 { |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1805 "link": ".../rest/data/issue/27", |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1806 "id": "27", |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1807 "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
|
1808 }, |
|
5695
3e1b66c4e1e2
Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents:
5688
diff
changeset
|
1809 ... |
|
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
|
1810 |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
1811 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
|
1812 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
|
1813 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
|
1814 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
|
1815 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
|
1816 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
|
1817 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
|
1818 |
|
5695
3e1b66c4e1e2
Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents:
5688
diff
changeset
|
1819 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
|
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 .../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
|
1822 |
|
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 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
|
1824 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
|
1825 |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1826 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
|
1827 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
|
1828 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
|
1829 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
|
1830 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
|
1831 |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1832 { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1833 "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
|
1834 "title": "Request for Broken PC", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1835 "id": "1001", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1836 "status": { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1837 "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
|
1838 "id": "6", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1839 "name": "resolved" |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1840 } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1841 } |
|
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
|
1842 |
|
5695
3e1b66c4e1e2
Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents:
5688
diff
changeset
|
1843 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
|
1844 |
|
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 === 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
|
1846 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
|
1847 === 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
|
1848 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
|
1849 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
|
1850 |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
1851 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
|
1852 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
|
1853 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1854 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1855 Programming the REST API |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
1856 ======================== |
|
5710
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1857 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1858 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
|
1859 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
|
1860 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
|
1861 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1862 Adding new rest endpoints |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
1863 ------------------------- |
|
5710
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1864 |
|
6765
b4bfbd768bc1
How to add dicttoxml at system or tracker level.
John Rouillard <rouilj@ieee.org>
parents:
6764
diff
changeset
|
1865 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
|
1866 directory. |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1867 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1868 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
|
1869 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1870 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
|
1871 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
|
1872 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1873 class RestfulInstance: |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1874 |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1875 @Routing.route("/summary2") |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1876 @_data_decorator |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1877 def summary2(self, input): |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1878 result = { "hello": "world" } |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1879 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
|
1880 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1881 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
|
1882 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1883 $ 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
|
1884 { |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1885 "data": { |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1886 "hello": "world" |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1887 } |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1888 } |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1889 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1890 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
|
1891 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1892 # 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
|
1893 @Routing.route("/data/<:class_name>/@schema", 'GET') |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1894 def get_element_schema(self, class_name, input): |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1895 result = { "schema": {} } |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1896 uid = self.db.getuid () |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1897 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
|
1898 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
|
1899 |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1900 class_obj = self.db.getclass(class_name) |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1901 props = class_obj.getprops(protected=False) |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1902 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
|
1903 |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1904 for prop in props: |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1905 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
|
1906 |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1907 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
|
1908 |
|
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 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
|
1911 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1912 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
|
1913 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1914 $ curl -X GET .../rest/data/issue/@schema |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1915 { |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1916 "schema": { |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1917 "keyword": { |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1918 "type": "<roundup.hyperdb.Multilink to \"keyword\">" |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1919 }, |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1920 "title": { |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1921 "type": "<roundup.hyperdb.String>" |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1922 }, |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1923 "files": { |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1924 "type": "<roundup.hyperdb.Multilink to \"file\">" |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1925 }, |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1926 "status": { |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1927 "type": "<roundup.hyperdb.Link to \"status\">" |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1928 }, ... |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1929 } |
|
5710
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1930 } |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1931 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1932 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1933 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
|
1934 ``/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
|
1935 |
|
5883
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1936 Redefine/move rest endpoints |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
1937 ---------------------------- |
|
5883
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1938 |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1939 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
|
1940 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
|
1941 |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1942 @Routing.route("/summary") |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1943 @_data_decorator |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1944 def summary2(self, input): |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1945 result = { "hello": "world" } |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1946 return 200, result |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1947 |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1948 will return:: |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1949 |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1950 { |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1951 "data": { |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1952 "hello": "world" |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1953 } |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1954 } |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1955 |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1956 |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1957 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
|
1958 endpoints to new locations. Adding:: |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1959 |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1960 @Routing.route("/data2/<:classname>") |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1961 def get_collection2(self, classname, input): |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1962 """ 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
|
1963 |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1964 Existing function is decorated with: |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1965 |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1966 @Routing.route("/data/<:classname>") |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1967 @_data_decorator |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1968 |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1969 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
|
1970 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
|
1971 """ |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1972 return self.get_collection(classname, input) |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1973 |
| 5886 | 1974 will make the response at /rest/data2/<class> be the same as what is |
| 1975 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
|
1976 |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1977 |
|
5843
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1978 Controlling Access to Backend Data |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
1979 ---------------------------------- |
|
5843
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1980 |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1981 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
|
1982 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
|
1983 seen. |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1984 |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1985 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
|
1986 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
|
1987 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
|
1988 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
|
1989 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
|
1990 users that are assignable to a task |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
1991 <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
|
1992 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
|
1993 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
|
1994 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
|
1995 permission. |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1996 |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1997 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
|
1998 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
|
1999 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
|
2000 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
|
2001 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
|
2002 |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
2003 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
|
2004 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
|
2005 |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
2006 class RestfulInstance(object): |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
2007 |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2008 @Routing.route("/data/@permission/Developer") |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2009 def get_role_Developer(self, input): |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2010 '''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
|
2011 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
|
2012 |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2013 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
|
2014 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
|
2015 specification if it specifies a property the user |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2016 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
|
2017 @verbose) are supported. |
|
5843
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
2018 |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2019 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
|
2020 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
|
2021 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
|
2022 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
|
2023 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
|
2024 search by a non-admin user. |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2025 ''' |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2026 # get real user id |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2027 realuid=self.db.getuid() |
|
5843
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
2028 |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2029 def allowed_field(fs): |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2030 if fs.name in ['username', 'realname' ]: |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2031 # only allow search matches for these fields |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2032 return True |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2033 elif fs.name in [ '@fields' ]: |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2034 for prop in fs.value.split(','): |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2035 # if any property is unviewable to user, remove |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2036 # @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
|
2037 # 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
|
2038 if not self.db.security.hasPermission( |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2039 'View', realuid, 'user', property=prop, |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2040 itemid='1'): |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2041 return False |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2042 return True |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2043 elif fs.name.startswith("@"): |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2044 # allow @page..., @verbose etc. |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2045 return True |
|
5843
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
2046 |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2047 # deny all other url parmeters |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2048 return False |
|
5843
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
2049 |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2050 # Cleanup input.list to prevent user from probing roles |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2051 # or viewing things the user should not be able to view. |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2052 input.list[:] = [ fs for fs in input.list |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2053 if allowed_field(fs) ] |
|
5843
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
2054 |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2055 # 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
|
2056 # search |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2057 input.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
|
2058 |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2059 # change user to acquire permission to search roles |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2060 self.db.setCurrentUser('admin') |
|
5843
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
2061 |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2062 # 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
|
2063 # 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
|
2064 # to get @verbose and other args supported. |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2065 return self.get_collection('user', input) |
|
5843
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
2066 |
|
5895
93bbe5340d5b
More typo fixes and verbatim blocks.
John Rouillard <rouilj@ieee.org>
parents:
5894
diff
changeset
|
2067 Calling this with:: |
|
93bbe5340d5b
More typo fixes and verbatim blocks.
John Rouillard <rouilj@ieee.org>
parents:
5894
diff
changeset
|
2068 |
|
93bbe5340d5b
More typo fixes and verbatim blocks.
John Rouillard <rouilj@ieee.org>
parents:
5894
diff
changeset
|
2069 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
|
2070 |
|
5843
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
2071 produces output similar to:: |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
2072 |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
2073 { |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2074 "data": { |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2075 "collection": [ |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2076 { |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2077 "username": "agent", |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2078 "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
|
2079 "realname": "James Bond", |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2080 "id": "4" |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2081 } |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2082 ], |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2083 "@total_size": 1 |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2084 } |
|
5843
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
2085 } |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
2086 |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
2087 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
|
2088 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
|
2089 ignored. |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
2090 |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2091 Changing Access Roles with JSON Web Tokens |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
2092 ------------------------------------------ |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2093 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2094 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
|
2095 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
|
2096 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
|
2097 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
|
2098 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
|
2099 issue. |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2100 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2101 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
|
2102 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
|
2103 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
|
2104 |
| 6165 | 2105 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
|
2106 you and have access to create a roundup timelog entry (see |
| 7353 | 2107 `<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
|
2108 to the associated issue. This should happen without sharing passwords |
| 6166 | 2109 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
|
2110 ``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
|
2111 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2112 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
|
2113 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
|
2114 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2115 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
|
2116 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2117 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
|
2118 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
|
2119 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
|
2120 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
|
2121 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
|
2122 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
|
2123 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
|
2124 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
|
2125 ``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
|
2126 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
|
2127 of ``openssl rand -base64 32``. |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2128 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
|
2129 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
|
2130 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2131 Create role |
|
5898
be8524335bfa
Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents:
5896
diff
changeset
|
2132 ~~~~~~~~~~~ |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2133 |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2134 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
|
2135 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
|
2136 |
|
5892
afb5705d1fe5
Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
5888
diff
changeset
|
2137 db.security.addRole(name="User:timelog", |
|
afb5705d1fe5
Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
5888
diff
changeset
|
2138 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
|
2139 |
|
afb5705d1fe5
Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
5888
diff
changeset
|
2140 db.security.addPermissionToRole('User:timelog', 'Rest Access') |
|
afb5705d1fe5
Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
5888
diff
changeset
|
2141 |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2142 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
|
2143 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
|
2144 db.security.addPermissionToRole("User:timelog", perm) |
|
5892
afb5705d1fe5
Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
5888
diff
changeset
|
2145 |
|
afb5705d1fe5
Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
5888
diff
changeset
|
2146 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
|
2147 properties=('id', 'times'), |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2148 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
|
2149 props_only=False) |
|
5892
afb5705d1fe5
Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
5888
diff
changeset
|
2150 db.security.addPermissionToRole("User:timelog", perm) |
|
afb5705d1fe5
Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
5888
diff
changeset
|
2151 |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2152 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
|
2153 properties=('id', 'times'), |
|
5893
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2154 description="Allow editing timelog for issue", |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2155 props_only=False) |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2156 db.security.addPermissionToRole("User:timelog", perm) |
|
5892
afb5705d1fe5
Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
5888
diff
changeset
|
2157 |
|
afb5705d1fe5
Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
5888
diff
changeset
|
2158 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
|
2159 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
|
2160 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
|
2161 role has the User role. |
|
afb5705d1fe5
Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
5888
diff
changeset
|
2162 |
|
afb5705d1fe5
Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
5888
diff
changeset
|
2163 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
|
2164 the issue. The etag is passed in the ``If-Match`` HTTP header when you |
| 5894 | 2165 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
|
2166 |
|
5892
afb5705d1fe5
Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
5888
diff
changeset
|
2167 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
|
2168 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
|
2169 ``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
|
2170 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
|
2171 value, and replace the ``times`` value. |
|
afb5705d1fe5
Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
5888
diff
changeset
|
2172 |
|
afb5705d1fe5
Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
5888
diff
changeset
|
2173 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
|
2174 value of the ``times`` value so your code can verify that it worked. |
|
afb5705d1fe5
Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
5888
diff
changeset
|
2175 This does potentially leak 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
|
2176 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2177 Create rest endpoints |
|
5898
be8524335bfa
Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents:
5896
diff
changeset
|
2178 ~~~~~~~~~~~~~~~~~~~~~ |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2179 |
|
5892
afb5705d1fe5
Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
5888
diff
changeset
|
2180 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
|
2181 only been tested with python3):: |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2182 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2183 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
|
2184 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2185 class RestfulInstance(object): |
|
5893
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2186 @Routing.route("/jwt/issue", 'POST') |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2187 @_data_decorator |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2188 def generate_jwt(self, input): |
|
6519
22cf6ee7ad88
jwt issue example: require input data, lowercase roles
John Rouillard <rouilj@ieee.org>
parents:
6384
diff
changeset
|
2189 """Create a JSON Web Token (jwt) |
|
22cf6ee7ad88
jwt issue example: require input data, lowercase roles
John Rouillard <rouilj@ieee.org>
parents:
6384
diff
changeset
|
2190 """ |
|
8022
f023b66c297d
doc: update JWT example to use utcnow from anypy_datetime_
John Rouillard <rouilj@ieee.org>
parents:
7980
diff
changeset
|
2191 import datetime |
|
5893
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2192 import jwt |
|
8022
f023b66c297d
doc: update JWT example to use utcnow from anypy_datetime_
John Rouillard <rouilj@ieee.org>
parents:
7980
diff
changeset
|
2193 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
|
2194 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
|
2195 |
|
5893
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2196 # 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
|
2197 # 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
|
2198 # 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
|
2199 # 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
|
2200 |
|
5893
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2201 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
|
2202 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
|
2203 try: |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2204 auth = self.client.env['HTTP_AUTHORIZATION'] |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2205 scheme, challenge = auth.split(' ', 1) |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2206 except (ValueError, AttributeError): |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2207 # bad format for header |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2208 raise Unauthorised(denialmsg) |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2209 if scheme.lower() != 'basic': |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2210 raise Unauthorised(denialmsg) |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2211 else: |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2212 raise Unauthorised(denialmsg) |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2213 |
|
6519
22cf6ee7ad88
jwt issue example: require input data, lowercase roles
John Rouillard <rouilj@ieee.org>
parents:
6384
diff
changeset
|
2214 # verify we have input data. |
|
22cf6ee7ad88
jwt issue example: require input data, lowercase roles
John Rouillard <rouilj@ieee.org>
parents:
6384
diff
changeset
|
2215 if not input: |
|
22cf6ee7ad88
jwt issue example: require input data, lowercase roles
John Rouillard <rouilj@ieee.org>
parents:
6384
diff
changeset
|
2216 raise UsageError("Missing data payload. " |
|
22cf6ee7ad88
jwt issue example: require input data, lowercase roles
John Rouillard <rouilj@ieee.org>
parents:
6384
diff
changeset
|
2217 "Verify Content-Type is sent") |
|
22cf6ee7ad88
jwt issue example: require input data, lowercase roles
John Rouillard <rouilj@ieee.org>
parents:
6384
diff
changeset
|
2218 |
|
5893
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2219 # 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
|
2220 # 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
|
2221 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
|
2222 rolenames = [] |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2223 for role in all_roles: |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2224 rolenames.append(role[0]) |
|
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 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
|
2227 |
|
5893
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2228 claim= { 'sub': self.db.getuid(), |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2229 'iss': self.db.config.TRACKER_WEB, |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2230 '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
|
2231 'iat': utcnow(), |
|
5893
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2232 } |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2233 |
|
5893
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2234 lifetime = 0 |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2235 if 'lifetime' in input: |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2236 if input['lifetime'].value != 'unlimited': |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2237 try: |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2238 lifetime = datetime.timedelta(seconds=int(input['lifetime'].value)) |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2239 except ValueError: |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2240 raise UsageError("Value 'lifetime' must be 'unlimited' or an integer to specify" + |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2241 " lifetime in seconds. Got %s."%input['lifetime'].value) |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2242 else: |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2243 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
|
2244 |
|
5893
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2245 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
|
2246 claim['exp'] = utcnow() + lifetime |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2247 |
|
5893
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2248 newroles = [] |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2249 if 'roles' in input: |
|
6519
22cf6ee7ad88
jwt issue example: require input data, lowercase roles
John Rouillard <rouilj@ieee.org>
parents:
6384
diff
changeset
|
2250 for role in [ r.lower() for r in input['roles'].value ]: |
|
5893
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2251 if role not in rolenames: |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2252 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
|
2253 if role in user_roles: |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2254 newroles.append(role) |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2255 continue |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2256 parentrole = role.split(':', 1)[0] |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2257 if parentrole in user_roles: |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2258 newroles.append(role) |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2259 continue |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2260 |
|
5893
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2261 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
|
2262 |
|
5893
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2263 claim['roles'] = newroles |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2264 else: |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2265 claim['roles'] = user_roles |
|
7809
be6cb2e0d471
feat: add support for rotating jwt keys
John Rouillard <rouilj@ieee.org>
parents:
7801
diff
changeset
|
2266 |
|
be6cb2e0d471
feat: add support for rotating jwt keys
John Rouillard <rouilj@ieee.org>
parents:
7801
diff
changeset
|
2267 # Sign with newest/first secret. |
|
be6cb2e0d471
feat: add support for rotating jwt keys
John Rouillard <rouilj@ieee.org>
parents:
7801
diff
changeset
|
2268 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
|
2269 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
|
2270 |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2271 # 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
|
2272 # 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
|
2273 result = {"jwt": b2s(myjwt), |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2274 } |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2275 |
|
5893
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2276 return 200, result |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2277 |
|
5893
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2278 @Routing.route("/jwt/validate", 'GET') |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2279 @_data_decorator |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2280 def validate_jwt(self,input): |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2281 import jwt |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2282 if not 'jwt' in input: |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2283 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
|
2284 |
|
5893
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2285 myjwt = input['jwt'].value |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2286 |
|
7809
be6cb2e0d471
feat: add support for rotating jwt keys
John Rouillard <rouilj@ieee.org>
parents:
7801
diff
changeset
|
2287 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
|
2288 |
|
be6cb2e0d471
feat: add support for rotating jwt keys
John Rouillard <rouilj@ieee.org>
parents:
7801
diff
changeset
|
2289 # 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
|
2290 # 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
|
2291 try: |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2292 result = jwt.decode(myjwt, secret, |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2293 algorithms=['HS256'], |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2294 audience=self.db.config.TRACKER_WEB, |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2295 issuer=self.db.config.TRACKER_WEB, |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2296 ) |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2297 except jwt.exceptions.InvalidTokenError as err: |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2298 return 401, str(err) |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2299 |
|
5893
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2300 return 200, result |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2301 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2302 **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
|
2303 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
|
2304 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
|
2305 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
|
2306 username/password authentication. |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2307 |
|
6764
32f52d14b496
Typo fixes, formatting fixes, jwt -> JWT, add link to JWT issue
John Rouillard <rouilj@ieee.org>
parents:
6681
diff
changeset
|
2308 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
|
2309 providing patches to existing code to: |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2310 |
|
7361
bc6bcffbed2a
rewrite JWT future to use refresh tokens.
John Rouillard <rouilj@ieee.org>
parents:
7353
diff
changeset
|
2311 1. create long lived refresh tokens |
|
bc6bcffbed2a
rewrite JWT future to use refresh tokens.
John Rouillard <rouilj@ieee.org>
parents:
7353
diff
changeset
|
2312 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
|
2313 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
|
2314 ignored by the roundup core |
|
bc6bcffbed2a
rewrite JWT future to use refresh tokens.
John Rouillard <rouilj@ieee.org>
parents:
7353
diff
changeset
|
2315 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
|
2316 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
|
2317 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2318 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
|
2319 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2320 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
|
2321 -H "X-requested-with: rest" \ |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2322 -H "Content-Type: application/json" \ |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2323 --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
|
2324 https://.../demo/rest/JWT/issue |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2325 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2326 (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
|
2327 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2328 { |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2329 "data": { |
|
6764
32f52d14b496
Typo fixes, formatting fixes, jwt -> JWT, add link to JWT issue
John Rouillard <rouilj@ieee.org>
parents:
6681
diff
changeset
|
2330 "JWT": "eyJ0eXAiOiJK......XxMDb-Q3oCnMpyhxPXMAk" |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2331 } |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2332 } |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2333 |
|
6764
32f52d14b496
Typo fixes, formatting fixes, jwt -> JWT, add link to JWT issue
John Rouillard <rouilj@ieee.org>
parents:
6681
diff
changeset
|
2334 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
|
2335 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
|
2336 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2337 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2338 curl -s -H "Referer: https://.../demo/" \ |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2339 -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
|
2340 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
|
2341 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2342 (note no login is required) which returns:: |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2343 |
|
5878
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 "data": { |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2346 "user": "3", |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2347 "roles": [ |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2348 "user:timelog" |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2349 ], |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2350 "iss": "https://.../demo/", |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2351 "aud": "https://.../demo/", |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2352 "iat": 1569542404, |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2353 "exp": 1569546004 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2354 } |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2355 } |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2356 |
|
6764
32f52d14b496
Typo fixes, formatting fixes, jwt -> JWT, add link to JWT issue
John Rouillard <rouilj@ieee.org>
parents:
6681
diff
changeset
|
2357 |
|
32f52d14b496
Typo fixes, formatting fixes, jwt -> JWT, add link to JWT issue
John Rouillard <rouilj@ieee.org>
parents:
6681
diff
changeset
|
2358 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
|
2359 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
|
2360 |
|
32f52d14b496
Typo fixes, formatting fixes, jwt -> JWT, add link to JWT issue
John Rouillard <rouilj@ieee.org>
parents:
6681
diff
changeset
|
2361 .. _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
|
2362 |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2363 Final steps |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
2364 ~~~~~~~~~~~ |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2365 |
| 5887 | 2366 See the `upgrading directions`_ on how to use the ``updateconfig`` |
| 5888 | 2367 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
|
2368 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
|
2369 (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
|
2370 ``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
|
2371 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2372 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
|
2373 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
|
2374 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
|
2375 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
|
2376 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
|
2377 https://issues.roundup-tracker.org/.) |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2378 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2379 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
|
2380 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
|
2381 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
|
2382 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
|
2383 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
|
2384 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
|
2385 |
|
5843
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
2386 |
|
5737
07d8bbf6ee5f
Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents:
5723
diff
changeset
|
2387 Creating Custom Rate Limits |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
2388 --------------------------- |
|
5737
07d8bbf6ee5f
Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents:
5723
diff
changeset
|
2389 |
|
5738
9777d7311bc0
Clean up the custom rate limit doc.
John Rouillard <rouilj@ieee.org>
parents:
5737
diff
changeset
|
2390 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
|
2391 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
|
2392 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
|
2393 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
|
2394 |
|
9777d7311bc0
Clean up the custom rate limit doc.
John Rouillard <rouilj@ieee.org>
parents:
5737
diff
changeset
|
2395 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
|
2396 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
|
2397 ``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
|
2398 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
|
2399 |
|
07d8bbf6ee5f
Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents:
5723
diff
changeset
|
2400 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
|
2401 from datetime import timedelta |
|
07d8bbf6ee5f
Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents:
5723
diff
changeset
|
2402 |
|
07d8bbf6ee5f
Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents:
5723
diff
changeset
|
2403 def grl(self): |
|
07d8bbf6ee5f
Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents:
5723
diff
changeset
|
2404 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
|
2405 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
|
2406 |
|
07d8bbf6ee5f
Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents:
5723
diff
changeset
|
2407 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
|
2408 |
|
07d8bbf6ee5f
Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents:
5723
diff
changeset
|
2409 uid = self.db.getuid() |
|
07d8bbf6ee5f
Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents:
5723
diff
changeset
|
2410 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
|
2411 node = class_obj.getnode(uid) |
|
07d8bbf6ee5f
Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents:
5723
diff
changeset
|
2412 |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2413 # 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
|
2414 user_calls = node.__getattr__('rate_limit_calls') |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2415 # 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
|
2416 user_interval = node.__getattr__('rate_limit_interval') |
|
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2417 |
|
5737
07d8bbf6ee5f
Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents:
5723
diff
changeset
|
2418 return RateLimit(user_calls or calls, |
|
7801
af898d1d66dc
doc: run sphinx-lint over docs.
John Rouillard <rouilj@ieee.org>
parents:
7733
diff
changeset
|
2419 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
|
2420 else: |
|
07d8bbf6ee5f
Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents:
5723
diff
changeset
|
2421 # 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
|
2422 return None |
|
07d8bbf6ee5f
Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents:
5723
diff
changeset
|
2423 |
|
07d8bbf6ee5f
Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents:
5723
diff
changeset
|
2424 RestfulInstance.getRateLimit = grl |
|
07d8bbf6ee5f
Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents:
5723
diff
changeset
|
2425 |
|
5738
9777d7311bc0
Clean up the custom rate limit doc.
John Rouillard <rouilj@ieee.org>
parents:
5737
diff
changeset
|
2426 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
|
2427 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
|
2428 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
|
2429 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
|
2430 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
2431 Test Examples |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
2432 ~~~~~~~~~~~~~ |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
2433 |
|
5895
93bbe5340d5b
More typo fixes and verbatim blocks.
John Rouillard <rouilj@ieee.org>
parents:
5894
diff
changeset
|
2434 Rate limit tests:: |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
2435 |
|
6765
b4bfbd768bc1
How to add dicttoxml at system or tracker level.
John Rouillard <rouilj@ieee.org>
parents:
6764
diff
changeset
|
2436 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
|
2437 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
|
2438 |
|
b4bfbd768bc1
How to add dicttoxml at system or tracker level.
John Rouillard <rouilj@ieee.org>
parents:
6764
diff
changeset
|
2439 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
|
2440 for the user identified by password. |
