Mercurial > p > roundup > code
annotate doc/rest.txt @ 7668:5b41018617f2
fix: out of memory error when importing under postgresql
If you try importing more than 20k items under postgresql you can run
out of memory:
psycopg2.errors.OutOfMemory: out of shared memory
HINT: You might need to increase max_locks_per_transaction.
Tuning memory may help, it's unknown at this point.
This checkin forces a commit to the postgres database after 10,000
rows have been added. This clears out the savepoints for each row and
starts a new transaction.
back_postgresql.py:
Implement commit mechanism in checkpoint_data(). Add two class level
attributes for tracking the number of savepoints and the limit when
the commit should happen.
roundup_admin.py:
implement pragma and dynamically create the config item
RDBMS_SAVEPOINT_LIMIT used by checkpoint_data.
Also fixed formatting of descriptions when using pragma list in
verbose mode.
admin_guide.txt, upgrading.txt:
Document change and use of pragma savepoint_limit in roundup-admin
for changing the default of 10,000.
test/db_test_base.py:
add some more asserts. In existing testAdminImportExport, set the
savepoint limit to 5 to test setting method and so that the commit
code will be run by existing tests. This provides coverage, but
does not actually test that the commit is done every 5 savepoints
8-(. The verification of every 5 savepoints was done manually
using a pdb breakpoint just before the commit.
acknowledgements.txt:
Added 2.4.0 section mentioning Norbert as he has done a ton of
testing with much larger datasets than I can test with.
| author | John Rouillard <rouilj@ieee.org> |
|---|---|
| date | Thu, 19 Oct 2023 16:11:25 -0400 |
| parents | c5307dc0e8c6 |
| children | 3eca3462ba0c |
| 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 |
|
7282
f86a4a712f1f
update metadata for rest.txt html page.
John Rouillard <rouilj@ieee.org>
parents:
7155
diff
changeset
|
4 Tracker. Enable REST access, endpoints, methods, |
|
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 |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
21 After the last 1.6.0 Release, a REST-API developed in 2015 during a |
|
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 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
71 Clients should set the header X-REQUESTED-WITH to any value and the |
|
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 |
|
7556
273c8c2b5042
fix(api): - issue2551063 - Rest/Xmlrpc interfaces needs failed login protection.
John Rouillard <rouilj@ieee.org>
parents:
7499
diff
changeset
|
80 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
|
81 ------------------------------- |
|
273c8c2b5042
fix(api): - issue2551063 - Rest/Xmlrpc interfaces needs failed login protection.
John Rouillard <rouilj@ieee.org>
parents:
7499
diff
changeset
|
82 |
|
273c8c2b5042
fix(api): - issue2551063 - Rest/Xmlrpc interfaces needs failed login protection.
John Rouillard <rouilj@ieee.org>
parents:
7499
diff
changeset
|
83 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
|
84 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
|
85 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
|
86 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
|
87 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
|
88 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
|
89 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
|
90 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
|
91 |
|
7600
5a8a41a2e3c8
docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents:
7582
diff
changeset
|
92 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
|
93 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
|
94 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
|
95 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
|
96 ``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
|
97 ``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
|
98 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
|
99 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
|
100 |
|
7600
5a8a41a2e3c8
docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents:
7582
diff
changeset
|
101 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
|
102 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
|
103 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
|
104 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
|
105 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
|
106 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
|
107 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
|
108 password every |
|
5a8a41a2e3c8
docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents:
7582
diff
changeset
|
109 ``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
|
110 |
|
7600
5a8a41a2e3c8
docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents:
7582
diff
changeset
|
111 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
|
112 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
|
113 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
|
114 the rate limiter. |
|
7556
273c8c2b5042
fix(api): - issue2551063 - Rest/Xmlrpc interfaces needs failed login protection.
John Rouillard <rouilj@ieee.org>
parents:
7499
diff
changeset
|
115 |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
116 Rate Limiting the API |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
117 --------------------- |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
118 |
|
7600
5a8a41a2e3c8
docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents:
7582
diff
changeset
|
119 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
|
120 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
|
121 |
|
7600
5a8a41a2e3c8
docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents:
7582
diff
changeset
|
122 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
|
123 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
|
124 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
|
125 documented in the same file. |
|
5660
d8d2b7724292
First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff
changeset
|
126 |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
127 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
|
128 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
|
129 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
|
130 ``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
|
131 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
|
132 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
|
133 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
|
134 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
|
135 ``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
|
136 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
|
137 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
|
138 60/sec and 3600/sec. |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
139 |
|
7600
5a8a41a2e3c8
docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents:
7582
diff
changeset
|
140 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
|
141 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
|
142 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
|
143 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
|
144 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
|
145 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
|
146 to the tracker admin. |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
147 |
|
7600
5a8a41a2e3c8
docs: rewrite segments using ahref paragraph rewriter.
John Rouillard <rouilj@ieee.org>
parents:
7582
diff
changeset
|
148 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
|
149 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
|
150 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
|
151 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
|
152 minimizes the loss. |
|
5660
d8d2b7724292
First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff
changeset
|
153 |
|
d8d2b7724292
First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff
changeset
|
154 Client API |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
155 ========== |
|
5660
d8d2b7724292
First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff
changeset
|
156 |
|
d8d2b7724292
First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff
changeset
|
157 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
|
158 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
|
159 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
|
160 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
|
161 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
162 Headers |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
163 ------- |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
164 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
165 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
|
166 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
167 **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
|
168 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
169 **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
|
170 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
171 **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
|
172 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
|
173 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
|
174 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
175 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
|
176 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
|
177 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
178 **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
|
179 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
180 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
|
181 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
182 **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
|
183 |
|
6182
acb9841bb4fd
Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents:
6167
diff
changeset
|
184 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
|
185 |
|
6206
b6f2cf872d2e
Expand sunset header explanation, fix formating missing `.
John Rouillard <rouilj@ieee.org>
parents:
6205
diff
changeset
|
186 **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
|
187 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
|
188 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
|
189 the REST endpoint will be going away. See |
| 7139 | 190 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
|
191 the sunset link type. |
|
6182
acb9841bb4fd
Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents:
6167
diff
changeset
|
192 |
|
6185
1cb2375015f0
Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents:
6182
diff
changeset
|
193 Hyperdb Stats |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
194 ------------- |
|
6185
1cb2375015f0
Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents:
6182
diff
changeset
|
195 |
|
1cb2375015f0
Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents:
6182
diff
changeset
|
196 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
|
197 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
|
198 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
|
199 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
|
200 like:: |
|
1cb2375015f0
Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents:
6182
diff
changeset
|
201 |
|
1cb2375015f0
Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents:
6182
diff
changeset
|
202 { "data": { |
|
1cb2375015f0
Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents:
6182
diff
changeset
|
203 ... |
|
1cb2375015f0
Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents:
6182
diff
changeset
|
204 "@stats": { |
|
1cb2375015f0
Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents:
6182
diff
changeset
|
205 "cache_hits": 3, |
|
1cb2375015f0
Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents:
6182
diff
changeset
|
206 "cache_misses": 1, |
|
1cb2375015f0
Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents:
6182
diff
changeset
|
207 "get_items": 0.0009722709655761719, |
|
1cb2375015f0
Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents:
6182
diff
changeset
|
208 "filtering": 0, |
|
1cb2375015f0
Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents:
6182
diff
changeset
|
209 "elapsed": 0.04731464385986328 |
|
1cb2375015f0
Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents:
6182
diff
changeset
|
210 } |
|
1cb2375015f0
Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents:
6182
diff
changeset
|
211 } |
|
1cb2375015f0
Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents:
6182
diff
changeset
|
212 } |
|
1cb2375015f0
Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents:
6182
diff
changeset
|
213 |
|
1cb2375015f0
Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents:
6182
diff
changeset
|
214 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
|
215 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
|
216 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
|
217 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
|
218 info. |
|
1cb2375015f0
Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents:
6182
diff
changeset
|
219 |
|
6182
acb9841bb4fd
Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents:
6167
diff
changeset
|
220 Versioning |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
221 ---------- |
|
6182
acb9841bb4fd
Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents:
6167
diff
changeset
|
222 |
|
acb9841bb4fd
Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents:
6167
diff
changeset
|
223 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
|
224 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
|
225 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
|
226 order, highest first): |
|
6182
acb9841bb4fd
Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents:
6167
diff
changeset
|
227 |
|
acb9841bb4fd
Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents:
6167
diff
changeset
|
228 1. Explicit version param in accept header: |
|
acb9841bb4fd
Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents:
6167
diff
changeset
|
229 ``application/json; version=1`` |
|
acb9841bb4fd
Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents:
6167
diff
changeset
|
230 |
|
acb9841bb4fd
Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents:
6167
diff
changeset
|
231 2. Version suffix in vendor accept header: |
|
acb9841bb4fd
Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents:
6167
diff
changeset
|
232 ``application/vnd.json.test-v1+json`` |
|
acb9841bb4fd
Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents:
6167
diff
changeset
|
233 |
|
7636
c5307dc0e8c6
docs: clarify Api version method priority; payload @apiver
John Rouillard <rouilj@ieee.org>
parents:
7600
diff
changeset
|
234 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
|
235 |
|
c5307dc0e8c6
docs: clarify Api version method priority; payload @apiver
John Rouillard <rouilj@ieee.org>
parents:
7600
diff
changeset
|
236 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
|
237 |
|
c5307dc0e8c6
docs: clarify Api version method priority; payload @apiver
John Rouillard <rouilj@ieee.org>
parents:
7600
diff
changeset
|
238 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
|
239 methods are used. |
|
6182
acb9841bb4fd
Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents:
6167
diff
changeset
|
240 |
|
acb9841bb4fd
Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents:
6167
diff
changeset
|
241 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
|
242 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
|
243 described above. |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
244 |
|
6311
be8d5a8e090a
Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents:
6288
diff
changeset
|
245 Input Formats |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
246 ------------- |
|
6311
be8d5a8e090a
Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents:
6288
diff
changeset
|
247 |
|
6384
66a061e52435
Test options in rest interface against live server; rest doc update
John Rouillard <rouilj@ieee.org>
parents:
6373
diff
changeset
|
248 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
|
249 not be sent. |
|
66a061e52435
Test options in rest interface against live server; rest doc update
John Rouillard <rouilj@ieee.org>
parents:
6373
diff
changeset
|
250 |
|
66a061e52435
Test options in rest interface against live server; rest doc update
John Rouillard <rouilj@ieee.org>
parents:
6373
diff
changeset
|
251 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
|
252 ``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
|
253 code 415. |
|
be8d5a8e090a
Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents:
6288
diff
changeset
|
254 |
|
6674
ff8845ca305e
issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents:
6630
diff
changeset
|
255 CORS preflight requests |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
256 ~~~~~~~~~~~~~~~~~~~~~~~ |
|
6674
ff8845ca305e
issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents:
6630
diff
changeset
|
257 |
|
ff8845ca305e
issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents:
6630
diff
changeset
|
258 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
|
259 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
|
260 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
|
261 available to the anonymous user and any authenticated user. The user |
|
ff8845ca305e
issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents:
6630
diff
changeset
|
262 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
|
263 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
|
264 run for preflight requests. |
|
6674
ff8845ca305e
issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents:
6630
diff
changeset
|
265 |
|
6681
ab2ed11c021e
issue2551205: Add support for specifying valid origins for api: xmlrpc/rest
John Rouillard <rouilj@ieee.org>
parents:
6675
diff
changeset
|
266 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
|
267 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
|
268 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
|
269 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
|
270 |
|
ab2ed11c021e
issue2551205: Add support for specifying valid origins for api: xmlrpc/rest
John Rouillard <rouilj@ieee.org>
parents:
6675
diff
changeset
|
271 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
|
272 the browser and must all be present: |
|
6674
ff8845ca305e
issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents:
6630
diff
changeset
|
273 |
|
ff8845ca305e
issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents:
6630
diff
changeset
|
274 * `Access-Control-Request-Headers` |
|
ff8845ca305e
issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents:
6630
diff
changeset
|
275 * `Access-Control-Request-Method` |
|
ff8845ca305e
issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents:
6630
diff
changeset
|
276 * `Origin` |
|
ff8845ca305e
issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents:
6630
diff
changeset
|
277 |
|
7155
89a59e46b3af
improve REST interface security
John Rouillard <rouilj@ieee.org>
parents:
7139
diff
changeset
|
278 The headers of the 204 response depend on the |
|
89a59e46b3af
improve REST interface security
John Rouillard <rouilj@ieee.org>
parents:
7139
diff
changeset
|
279 ``allowed_api_origins`` setting. If a ``*`` is included as the |
|
89a59e46b3af
improve REST interface security
John Rouillard <rouilj@ieee.org>
parents:
7139
diff
changeset
|
280 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
|
281 provide authentication. This limits the available data to what |
|
89a59e46b3af
improve REST interface security
John Rouillard <rouilj@ieee.org>
parents:
7139
diff
changeset
|
282 the anonymous user can see in the web interface. |
|
89a59e46b3af
improve REST interface security
John Rouillard <rouilj@ieee.org>
parents:
7139
diff
changeset
|
283 |
|
89a59e46b3af
improve REST interface security
John Rouillard <rouilj@ieee.org>
parents:
7139
diff
changeset
|
284 All 204 responses will include the headers: |
|
6674
ff8845ca305e
issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents:
6630
diff
changeset
|
285 |
|
ff8845ca305e
issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents:
6630
diff
changeset
|
286 * `Access-Control-Allow-Origin` |
|
ff8845ca305e
issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents:
6630
diff
changeset
|
287 * `Access-Control-Allow-Headers` |
|
ff8845ca305e
issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents:
6630
diff
changeset
|
288 * `Access-Control-Allow-Methods` |
|
ff8845ca305e
issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents:
6630
diff
changeset
|
289 * `Access-Control-Max-Age: 86400` |
|
ff8845ca305e
issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents:
6630
diff
changeset
|
290 |
|
7155
89a59e46b3af
improve REST interface security
John Rouillard <rouilj@ieee.org>
parents:
7139
diff
changeset
|
291 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
|
292 ``allowed_api_origins`` it will also include: |
|
89a59e46b3af
improve REST interface security
John Rouillard <rouilj@ieee.org>
parents:
7139
diff
changeset
|
293 |
|
89a59e46b3af
improve REST interface security
John Rouillard <rouilj@ieee.org>
parents:
7139
diff
changeset
|
294 * `Access-Control-Allow-Credentials: true` |
|
89a59e46b3af
improve REST interface security
John Rouillard <rouilj@ieee.org>
parents:
7139
diff
changeset
|
295 |
|
89a59e46b3af
improve REST interface security
John Rouillard <rouilj@ieee.org>
parents:
7139
diff
changeset
|
296 permitting the client to log in and perform authenticated operations. |
|
89a59e46b3af
improve REST interface security
John Rouillard <rouilj@ieee.org>
parents:
7139
diff
changeset
|
297 |
|
6674
ff8845ca305e
issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents:
6630
diff
changeset
|
298 If the endpoint accepts the PATCH verb the header `Accept-Patch` with |
|
ff8845ca305e
issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents:
6630
diff
changeset
|
299 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
|
300 multipart/form-data`) will be included. |
|
ff8845ca305e
issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents:
6630
diff
changeset
|
301 |
|
ff8845ca305e
issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents:
6630
diff
changeset
|
302 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
|
303 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
|
304 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
|
305 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
|
306 `Creating Custom Rate Limits`_ |
|
ff8845ca305e
issue2551203 - CORS and CORS preflight documentation.
John Rouillard <rouilj@ieee.org>
parents:
6630
diff
changeset
|
307 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
|
308 |
|
6311
be8d5a8e090a
Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents:
6288
diff
changeset
|
309 Response Formats |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
310 ---------------- |
|
6311
be8d5a8e090a
Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents:
6288
diff
changeset
|
311 |
|
be8d5a8e090a
Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents:
6288
diff
changeset
|
312 The default response format is json. |
|
be8d5a8e090a
Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents:
6288
diff
changeset
|
313 |
|
be8d5a8e090a
Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents:
6288
diff
changeset
|
314 If you add the ``dicttoxml.py`` module you can request XML formatted |
|
be8d5a8e090a
Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents:
6288
diff
changeset
|
315 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
|
316 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
|
317 |
|
6765
b4bfbd768bc1
How to add dicttoxml at system or tracker level.
John Rouillard <rouilj@ieee.org>
parents:
6764
diff
changeset
|
318 ``dicttoxml.py`` should be installed in the Python install directory, |
|
b4bfbd768bc1
How to add dicttoxml at system or tracker level.
John Rouillard <rouilj@ieee.org>
parents:
6764
diff
changeset
|
319 or the file can be added to the Roundup installation directory long |
|
b4bfbd768bc1
How to add dicttoxml at system or tracker level.
John Rouillard <rouilj@ieee.org>
parents:
6764
diff
changeset
|
320 ide ``rest.py``. It can also be enabled on a per tracker basis by |
|
b4bfbd768bc1
How to add dicttoxml at system or tracker level.
John Rouillard <rouilj@ieee.org>
parents:
6764
diff
changeset
|
321 adding ``dicttoxml.py`` to the lib directory in your tracker home (you |
|
b4bfbd768bc1
How to add dicttoxml at system or tracker level.
John Rouillard <rouilj@ieee.org>
parents:
6764
diff
changeset
|
322 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
|
323 `interfaces.py`_ to enable xml:: |
|
b4bfbd768bc1
How to add dicttoxml at system or tracker level.
John Rouillard <rouilj@ieee.org>
parents:
6764
diff
changeset
|
324 |
|
b4bfbd768bc1
How to add dicttoxml at system or tracker level.
John Rouillard <rouilj@ieee.org>
parents:
6764
diff
changeset
|
325 from roundup import rest |
|
b4bfbd768bc1
How to add dicttoxml at system or tracker level.
John Rouillard <rouilj@ieee.org>
parents:
6764
diff
changeset
|
326 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
|
327 |
|
b4bfbd768bc1
How to add dicttoxml at system or tracker level.
John Rouillard <rouilj@ieee.org>
parents:
6764
diff
changeset
|
328 rest.dicttoxml = dtox |
|
b4bfbd768bc1
How to add dicttoxml at system or tracker level.
John Rouillard <rouilj@ieee.org>
parents:
6764
diff
changeset
|
329 |
|
b4bfbd768bc1
How to add dicttoxml at system or tracker level.
John Rouillard <rouilj@ieee.org>
parents:
6764
diff
changeset
|
330 .. _interfaces.py: customizing.html#interfaces-py-hooking-into-the-core-of-roundup |
|
b4bfbd768bc1
How to add dicttoxml at system or tracker level.
John Rouillard <rouilj@ieee.org>
parents:
6764
diff
changeset
|
331 |
|
6311
be8d5a8e090a
Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents:
6288
diff
changeset
|
332 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
|
333 ``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
|
334 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
|
335 |
|
be8d5a8e090a
Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents:
6288
diff
changeset
|
336 To make testing from the browser easier, you can also append the |
|
be8d5a8e090a
Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents:
6288
diff
changeset
|
337 extension `.json` or `.xml` to the path component of the url. This |
|
be8d5a8e090a
Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents:
6288
diff
changeset
|
338 will force json or xml (if supported) output. If you use an extension |
|
be8d5a8e090a
Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents:
6288
diff
changeset
|
339 it takes priority over any accept headers. |
|
be8d5a8e090a
Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents:
6288
diff
changeset
|
340 |
|
be8d5a8e090a
Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents:
6288
diff
changeset
|
341 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
|
342 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
|
343 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
|
344 |
|
be8d5a8e090a
Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents:
6288
diff
changeset
|
345 |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
346 General Guidelines |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
347 ------------------ |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
348 |
| 5854 | 349 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
|
350 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
|
351 ``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
|
352 ``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
|
353 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
|
354 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
|
355 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
|
356 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
|
357 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
|
358 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
|
359 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
360 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
|
361 ``@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
|
362 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
|
363 |
|
6311
be8d5a8e090a
Fix uncaught error when parsing rest headers, document
John Rouillard <rouilj@ieee.org>
parents:
6288
diff
changeset
|
364 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
|
365 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
|
366 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
367 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
|
368 ``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
|
369 well as a ``collections`` list of objects:: |
|
5660
d8d2b7724292
First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff
changeset
|
370 |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
371 { "data": { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
372 "meta data field1": "value", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
373 "meta data field2": "value", |
| 5854 | 374 "collection": [ |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
375 { "link": "url to item", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
376 "id": "internal identifier for item" }, |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
377 { "link": "url to second item", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
378 "id": "id item 2" }, |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
379 ... ] |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
380 "@links": { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
381 "relation": [ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
382 { "rel": "relation/subrelation", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
383 "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
|
384 ... |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
385 ], |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
386 "relation2": [ {...} ], ... |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
387 } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
388 } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
389 } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
390 |
| 5854 | 391 available meta data is described in the documentation for the |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
392 collections endpoint. |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
393 |
|
6207
8a21f8ba3065
Doc updates. Mostly formatting.
John Rouillard <rouilj@ieee.org>
parents:
6206
diff
changeset
|
394 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
|
395 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
|
396 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
|
397 |
|
6207
8a21f8ba3065
Doc updates. Mostly formatting.
John Rouillard <rouilj@ieee.org>
parents:
6206
diff
changeset
|
398 .. _HATEOS: https://en.wikipedia.org/wiki/HATEOAS |
|
8a21f8ba3065
Doc updates. Mostly formatting.
John Rouillard <rouilj@ieee.org>
parents:
6206
diff
changeset
|
399 |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
400 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
|
401 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
|
402 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
|
403 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
|
404 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
|
405 represented. |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
406 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
407 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
|
408 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
|
409 ``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
|
410 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
|
411 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
|
412 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
|
413 conflicts with the self url. |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
414 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
415 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
|
416 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
|
417 ``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
|
418 the issue. Example:: |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
419 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
420 { "data": { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
421 "meta data field1": "value", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
422 "type": "type of item, issue, user ..." |
| 5854 | 423 "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
|
424 "attributes": { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
425 "title": "title of issue", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
426 "nosy": [ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
427 { "link": "url for user4", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
428 "id": "4" } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
429 ], |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
430 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
431 ... } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
432 } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
433 } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
434 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
435 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
|
436 ``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
|
437 the property. This ``data`` subfield may be a simple string (all types |
| 5854 | 438 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
|
439 properties). Example:: |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
440 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
441 { "data": { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
442 "type": "description of class", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
443 "@etag": "\"f15e6942f00a41960de45f9413684591\"", |
| 5854 | 444 "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
|
445 "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
|
446 "data": "value of property" |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
447 } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
448 } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
449 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
450 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
451 Special Endpoints |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
452 ----------------- |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
453 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
454 There are a few special endpoints that provide some additional data. |
| 5854 | 455 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
|
456 "Programming the REST API"_ below. |
|
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 /summary |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
459 ~~~~~~~~ |
|
5660
d8d2b7724292
First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff
changeset
|
460 |
|
5695
3e1b66c4e1e2
Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents:
5688
diff
changeset
|
461 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
|
462 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
|
463 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
|
464 |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
465 /data |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
466 ~~~~~ |
|
5660
d8d2b7724292
First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff
changeset
|
467 |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
468 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
|
469 |
|
d8d2b7724292
First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff
changeset
|
470 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
|
471 classes can be reached via ``/data/<classname>`` where ``<classname>`` |
|
d8d2b7724292
First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff
changeset
|
472 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
|
473 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
|
474 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
|
475 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
|
476 ``/data/issue/42/title``. |
|
d8d2b7724292
First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff
changeset
|
477 |
|
5723
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 All the links mentioned in the following support the http method ``GET``. |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
480 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
|
481 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
|
482 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
483 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
|
484 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
485 /data/\ *class* Collection |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
486 -------------------------- |
|
5723
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 When performing the ``GET`` method on a class (e.g. ``/data/issue``), |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
489 the ``data`` object includes the number of items available in |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
490 ``@total_size``. A a ``collection`` list follows which contains the id |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
491 and link to the respective item. For example a get on |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
492 https://.../rest/data/issue returns:: |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
493 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
494 { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
495 "data": { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
496 "collection": [ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
497 { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
498 "id": "1", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
499 "link": "https://.../rest/data/issue/1" |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
500 }, |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
501 { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
502 "id": "100", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
503 "link": "https://.../rest/data/issue/100" |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
504 } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
505 ... |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
506 ], |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
507 "@total_size": 171 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
508 } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
509 } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
510 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
511 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
|
512 sections. |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
513 |
|
5982
88316ac61ab0
Add warning about collection size limit as anti-DOS mechanism.
John Rouillard <rouilj@ieee.org>
parents:
5933
diff
changeset
|
514 A server may implement a default maximum number of items in the |
|
88316ac61ab0
Add warning about collection size limit as anti-DOS mechanism.
John Rouillard <rouilj@ieee.org>
parents:
5933
diff
changeset
|
515 collection. This can be used to prevent denial of service (DOS). As |
|
88316ac61ab0
Add warning about collection size limit as anti-DOS mechanism.
John Rouillard <rouilj@ieee.org>
parents:
5933
diff
changeset
|
516 a result all clients must be programmed to expect pagination |
|
88316ac61ab0
Add warning about collection size limit as anti-DOS mechanism.
John Rouillard <rouilj@ieee.org>
parents:
5933
diff
changeset
|
517 decorations in the response. See the section on pagination below for |
|
88316ac61ab0
Add warning about collection size limit as anti-DOS mechanism.
John Rouillard <rouilj@ieee.org>
parents:
5933
diff
changeset
|
518 details. |
|
88316ac61ab0
Add warning about collection size limit as anti-DOS mechanism.
John Rouillard <rouilj@ieee.org>
parents:
5933
diff
changeset
|
519 |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
520 Searching |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
521 ~~~~~~~~~ |
|
5723
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 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
|
524 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
|
525 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
526 .. list-table:: Query Parameters Examples |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
527 :header-rows: 1 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
528 :widths: 20 20 80 |
|
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
|
529 |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
530 * - Query parameter |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
531 - Field type |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
532 - Explanation |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
533 * - ``title=foo`` |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
534 - String |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
535 - 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
|
536 in the title. |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
537 * - ``status=2`` |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
538 - Link |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
539 - 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
|
540 * - ``status=open`` |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
541 - Link |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
542 - 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
|
543 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
|
544 * - ``nosy=1`` |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
545 - MultiLink |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
546 - 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
|
547 * - ``nosy=admin`` |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
548 - MultiLink |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
549 - 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
|
550 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
|
551 * - ``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
|
552 values match false. |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
553 - Boolean |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
554 - 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
|
555 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
556 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
|
557 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
|
558 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
|
559 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
|
560 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
|
561 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
|
562 |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
563 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
|
564 performs a case-insensitive substring search. Searching for |
|
5898
be8524335bfa
Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents:
5896
diff
changeset
|
565 ``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
|
566 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
|
567 |
|
a592e3156134
Added more verbage on "Rest Access" permission and reworked search docs.
John Rouillard <rouilj@ieee.org>
parents:
5898
diff
changeset
|
568 Changing the search to ``title:=Something`` (note the `:`) performs an |
|
a592e3156134
Added more verbage on "Rest Access" permission and reworked search docs.
John Rouillard <rouilj@ieee.org>
parents:
5898
diff
changeset
|
569 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
|
570 with a capital ``S``. Another example is: |
|
5898
be8524335bfa
Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents:
5896
diff
changeset
|
571 ``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
|
572 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
|
573 ``%20`` will also work. Note that you must match the spaces when |
|
be8524335bfa
Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents:
5896
diff
changeset
|
574 performing exact matches. So `title:=test++that+nosy+actually+works.`` |
|
5901
a592e3156134
Added more verbage on "Rest Access" permission and reworked search docs.
John Rouillard <rouilj@ieee.org>
parents:
5898
diff
changeset
|
575 matches the word ``test`` with two spaces bewteen ``test`` and |
|
a592e3156134
Added more verbage on "Rest Access" permission and reworked search docs.
John Rouillard <rouilj@ieee.org>
parents:
5898
diff
changeset
|
576 ``that`` in the title. |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
577 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
578 To make this clear, searching |
|
5898
be8524335bfa
Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents:
5896
diff
changeset
|
579 ``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
|
580 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
|
581 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
|
582 ``name`` using ``https://.../rest/data/keyword?name=Foo`` (note |
|
be8524335bfa
Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents:
5896
diff
changeset
|
583 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
|
584 ``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
|
585 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
586 In all cases the field ``@total_size`` is reported which is the total |
| 5854 | 587 number of items available if you were to retrieve all of them. |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
588 |
|
6288
9d132769ed37
Add missing comma to rest.txt.
John Rouillard <rouilj@ieee.org>
parents:
6261
diff
changeset
|
589 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
|
590 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
|
591 body of a msg) is a work in progress. |
|
be8524335bfa
Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents:
5896
diff
changeset
|
592 |
|
be8524335bfa
Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents:
5896
diff
changeset
|
593 .. _URL Encoding: https://en.wikipedia.org/wiki/Percent-encoding |
|
be8524335bfa
Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents:
5896
diff
changeset
|
594 |
|
be8524335bfa
Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents:
5896
diff
changeset
|
595 Transitive Searching |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
596 ^^^^^^^^^^^^^^^^^^^^ |
|
5898
be8524335bfa
Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents:
5896
diff
changeset
|
597 |
|
be8524335bfa
Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents:
5896
diff
changeset
|
598 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
|
599 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
|
600 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
|
601 (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
|
602 using: ``/issues?messages.author=admin``. Note that this requires |
|
be8524335bfa
Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents:
5896
diff
changeset
|
603 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
|
604 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
|
605 present, the search will silently drop the attribute. |
|
be8524335bfa
Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents:
5896
diff
changeset
|
606 |
|
be8524335bfa
Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents:
5896
diff
changeset
|
607 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
|
608 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
|
609 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
|
610 ``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
|
611 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
|
612 |
|
be8524335bfa
Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents:
5896
diff
changeset
|
613 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
|
614 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
|
615 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
|
616 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
|
617 |
|
5865
04deafac71ab
Implement sorting of collections in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents:
5863
diff
changeset
|
618 Sorting |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
619 ~~~~~~~ |
|
5865
04deafac71ab
Implement sorting of collections in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents:
5863
diff
changeset
|
620 |
|
04deafac71ab
Implement sorting of collections in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents:
5863
diff
changeset
|
621 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
|
622 ``@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
|
623 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
|
624 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
|
625 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
|
626 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
|
627 and then by id of an issue:: |
|
04deafac71ab
Implement sorting of collections in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents:
5863
diff
changeset
|
628 |
|
04deafac71ab
Implement sorting of collections in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents:
5863
diff
changeset
|
629 @sort=status,-id |
|
04deafac71ab
Implement sorting of collections in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents:
5863
diff
changeset
|
630 |
|
04deafac71ab
Implement sorting of collections in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents:
5863
diff
changeset
|
631 |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
632 Pagination |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
633 ~~~~~~~~~~ |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
634 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
635 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
|
636 parameters ``@page_size`` and ``@page_index`` (Note the use of the |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
637 leading `@` to make the parameters distinguishable from field names.) |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
638 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
639 .. list-table:: Query Parameters Examples |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
640 :header-rows: 1 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
641 :widths: 20 80 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
642 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
643 * - Query parameter |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
644 - Explanation |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
645 * - ``@page_size`` |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
646 - 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
|
647 ``@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
|
648 * - ``@page_index`` |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
649 - (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
|
650 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
|
651 |
| 5854 | 652 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
|
653 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
|
654 |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
655 { "data": |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
656 { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
657 "collection": { ... }, |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
658 "@total_size": 222, |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
659 "@links": { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
660 "self": [ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
661 { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
662 "uri": |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
663 "https://.../rest/data/issue?@page_index=1&@fields=status&@page_size=5", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
664 "rel": "self" |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
665 } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
666 ], |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
667 "next": [ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
668 { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
669 "uri": |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
670 "https://.../rest/data/issue?@page_index=2&@fields=status&@page_size=5", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
671 "rel": "next" |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
672 } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
673 ] |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
674 } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
675 } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
676 } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
677 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
678 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
|
679 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
|
680 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
|
681 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
|
682 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
|
683 (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
|
684 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
|
685 |
|
5982
88316ac61ab0
Add warning about collection size limit as anti-DOS mechanism.
John Rouillard <rouilj@ieee.org>
parents:
5933
diff
changeset
|
686 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
|
687 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
|
688 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
|
689 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
|
690 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
691 Field embedding and verbose output |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
692 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
693 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
694 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
|
695 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
|
696 ``@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
|
697 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
|
698 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
699 .. list-table:: Query Parameters Examples |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
700 :header-rows: 1 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
701 :widths: 20 80 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
702 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
703 * - Query parameter |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
704 - Explanation |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
705 * - ``@verbose=0`` |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
706 - each item in the collection has its "id" property displayed |
| 5854 | 707 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
|
708 * - ``@verbose=1`` |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
709 - 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
|
710 is the default. |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
711 * - ``@verbose=2`` |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
712 - 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
|
713 addition to "id" property and a link for the item. |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
714 This is useful as documented below in "Searches and selection"_. |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
715 * - ``@verbose=3`` |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
716 - 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
|
717 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
|
718 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
|
719 * - ``@fields=status,title`` |
|
5824
352e78c3b4ab
Allow @fields to include protected properties, document @protected
John Rouillard <rouilj@ieee.org>
parents:
5738
diff
changeset
|
720 - 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
|
721 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
|
722 @verbose parameter. Protected properties |
|
352e78c3b4ab
Allow @fields to include protected properties, document @protected
John Rouillard <rouilj@ieee.org>
parents:
5738
diff
changeset
|
723 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
|
724 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
725 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
|
726 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
|
727 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
|
728 ``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
|
729 for an issue is its title. |
|
e097ff5064b8
Allow transitive properties in @fields in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents:
5982
diff
changeset
|
730 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
|
731 ``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
|
732 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
|
733 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
|
734 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
|
735 ``@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
|
736 ``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
|
737 |
|
6090
e097ff5064b8
Allow transitive properties in @fields in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents:
5982
diff
changeset
|
738 |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
739 { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
740 "data": { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
741 "collection": [ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
742 { |
|
6090
e097ff5064b8
Allow transitive properties in @fields in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents:
5982
diff
changeset
|
743 "link": "https://.../rest/data/issue/1", |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
744 "title": "Welcome to the tracker START HERE", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
745 "id": "1", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
746 "status": { |
|
6090
e097ff5064b8
Allow transitive properties in @fields in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents:
5982
diff
changeset
|
747 "link": "https://.../rest/data/status/1", |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
748 "id": "1", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
749 "name": "new" |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
750 } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
751 }, |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
752 ... |
|
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 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
|
756 ``@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
|
757 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
|
758 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
759 { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
760 "data": { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
761 "collection": [ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
762 { |
|
6764
32f52d14b496
Typo fixes, formatting fixes, jwt -> JWT, add link to JWT issue
John Rouillard <rouilj@ieee.org>
parents:
6681
diff
changeset
|
763 "link": "https://.../rest/data/issue/1", |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
764 "id": "1", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
765 "status": { |
|
6764
32f52d14b496
Typo fixes, formatting fixes, jwt -> JWT, add link to JWT issue
John Rouillard <rouilj@ieee.org>
parents:
6681
diff
changeset
|
766 "link": "https://.../rest/data/status/1", |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
767 "id": "1" |
|
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 }, |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
770 ... |
|
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 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
773 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
|
774 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
|
775 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
|
776 output. |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
777 |
| 5854 | 778 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
|
779 items in the collection. |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
780 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
781 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
|
782 by these features. |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
783 |
|
5928
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
784 Getting Message and Files Content |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
785 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
5928
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
786 |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
787 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
|
788 ``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
|
789 |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
790 { |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
791 "data": { |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
792 "id": "11", |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
793 "type": "msg", |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
794 "link": "https://.../demo/rest/data/msg/11", |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
795 "attributes": { |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
796 "author": { |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
797 "id": "5", |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
798 "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
|
799 }, |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
800 "content": { |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
801 "link": "https://.../demo/msg11/" |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
802 }, |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
803 "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
|
804 "files": [], |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
805 "inreplyto": null, |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
806 "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
|
807 "messagetype": { |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
808 "id": "1", |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
809 "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
|
810 }, |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
811 "recipients": [ |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
812 { |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
813 "id": "1", |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
814 "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
|
815 }, |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
816 { |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
817 "id": "3", |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
818 "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
|
819 }, |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
820 { |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
821 "id": "4", |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
822 "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
|
823 } |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
824 ], |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
825 "subject": null, |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
826 "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
|
827 }, |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
828 "@etag": "\"584f82231079e349031bbb853747df1c\"" |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
829 } |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
830 } |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
831 |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
832 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
|
833 ``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
|
834 /, 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
|
835 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
|
836 |
|
6630
0351caa802f7
Add missing url in example.
John Rouillard <rouilj@ieee.org>
parents:
6586
diff
changeset
|
837 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
|
838 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
|
839 like:: |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
840 |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
841 ... |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
842 "author": { |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
843 "id": "5", |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
844 "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
|
845 }, |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
846 "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
|
847 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
|
848 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
|
849 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
|
850 "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
|
851 ... |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
852 |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
853 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
|
854 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
|
855 |
|
5929
0368d75de544
issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents:
5928
diff
changeset
|
856 Retrieving the contents of a file is similar. Performing a |
|
0368d75de544
issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents:
5928
diff
changeset
|
857 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
|
858 |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
859 { |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
860 "data": { |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
861 "id": "11", |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
862 "type": "file", |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
863 "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
|
864 "attributes": { |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
865 "acl": null, |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
866 "content": { |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
867 "link": "https://.../demo/file11/" |
|
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 "name": "afile", |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
870 "status": { |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
871 "id": "1", |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
872 "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
|
873 }, |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
874 "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
|
875 }, |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
876 "@etag": "\"74276f75ef71a30a0cce62dc6a8aa1bb\"" |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
877 } |
|
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 |
|
5929
0368d75de544
issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents:
5928
diff
changeset
|
880 To download the file contents for this example you would |
|
0368d75de544
issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents:
5928
diff
changeset
|
881 perform an http GET using: ``https://.../demo/file11/``. The trailing |
|
0368d75de544
issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents:
5928
diff
changeset
|
882 / 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
|
883 application/octet-stream. |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
884 |
|
5929
0368d75de544
issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents:
5928
diff
changeset
|
885 If you perform a get on |
|
0368d75de544
issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents:
5928
diff
changeset
|
886 ``https://.../demo/rest/data/file/11?@verbose=3`` the content field |
|
0368d75de544
issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents:
5928
diff
changeset
|
887 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
|
888 |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
889 "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
|
890 property. mdsum: bd990c0f8833dd991daf610b81b62316", |
|
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 |
|
5929
0368d75de544
issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents:
5928
diff
changeset
|
893 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
|
894 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
|
895 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
896 Other query params |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
897 ~~~~~~~~~~~~~~~~~~ |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
898 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
899 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
|
900 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
901 .. list-table:: Query Parameters Examples |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
902 :header-rows: 1 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
903 :widths: 20 80 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
904 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
905 * - Query parameter |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
906 - Explanation |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
907 * - ``@pretty=false`` |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
908 - 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
|
909 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
|
910 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
|
911 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
|
912 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
|
913 this time. |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
914 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
915 Using the POST method |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
916 ~~~~~~~~~~~~~~~~~~~~~ |
|
5660
d8d2b7724292
First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff
changeset
|
917 |
|
d8d2b7724292
First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff
changeset
|
918 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
|
919 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
|
920 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
|
921 parameters as the GET method after successful creation. |
|
d8d2b7724292
First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff
changeset
|
922 |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
923 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
|
924 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
|
925 |
|
d8d2b7724292
First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff
changeset
|
926 |
|
5710
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
927 Safely Re-sending POST |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
928 ^^^^^^^^^^^^^^^^^^^^^^ |
|
5710
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
929 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
930 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
|
931 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
|
932 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
|
933 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
|
934 |
|
5710
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
935 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
|
936 Once Exactly spec: |
| 7139 | 937 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
|
938 |
|
5710
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
939 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
|
940 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
|
941 |
|
5710
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
942 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
|
943 |
|
5710
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
944 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
|
945 -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
|
946 -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
|
947 --data '' \ |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
948 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
|
949 |
|
5710
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
950 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
|
951 |
|
5710
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
952 { |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
953 "data": { |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
954 "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
|
955 "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
|
956 } |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
957 } |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
958 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
959 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
|
960 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
|
961 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
|
962 |
|
5710
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
963 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
|
964 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
|
965 ``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
|
966 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
967 For example:: |
|
5688
1b9ef04b9528
Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents:
5678
diff
changeset
|
968 |
|
5710
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
969 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
|
970 -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
|
971 -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
|
972 -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
|
973 --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
|
974 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
|
975 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
976 returns:: |
|
5688
1b9ef04b9528
Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents:
5678
diff
changeset
|
977 |
|
5710
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
978 { |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
979 "data": { |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
980 "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
|
981 "id": "2280" |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
982 } |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
983 } |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
984 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
985 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
|
986 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
|
987 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
|
988 |
|
6261
424f70c076b9
Grammar fix. Remove word missed in rewrite.
John Rouillard <rouilj@ieee.org>
parents:
6207
diff
changeset
|
989 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
|
990 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
|
991 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
|
992 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
|
993 |
|
5710
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
994 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
|
995 -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
|
996 --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
|
997 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
|
998 |
|
5710
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
999 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
|
1000 |
|
5710
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1001 { |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1002 "data": { |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1003 "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
|
1004 "link": |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1005 "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
|
1006 } |
|
5710
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1007 } |
|
5688
1b9ef04b9528
Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents:
5678
diff
changeset
|
1008 |
|
5710
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1009 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
|
1010 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
|
1011 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
|
1012 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1013 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
|
1014 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
|
1015 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
|
1016 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1017 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
|
1018 |
|
5710
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1019 * 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
|
1020 * 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
|
1021 * 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
|
1022 fails |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1023 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1024 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
|
1025 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
|
1026 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
|
1027 mechanism. |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1028 |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1029 .. [#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
|
1030 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
|
1031 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
|
1032 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
|
1033 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
|
1034 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
|
1035 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
|
1036 response was lost. |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1037 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1038 Other Supported Methods for Collections |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
1039 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1040 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1041 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
|
1042 allowed on a given endpoint. |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1043 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1044 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
|
1045 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1046 /data/\ *class*/\ *id* item |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
1047 --------------------------- |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1048 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1049 When performing the ``GET`` method on an item |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1050 (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
|
1051 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
|
1052 (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
|
1053 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
|
1054 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1055 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
|
1056 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
|
1057 account used for the query. |
|
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 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
|
1060 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
|
1061 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
|
1062 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
|
1063 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
|
1064 transitive properties. By default protected |
|
5892
afb5705d1fe5
Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
5888
diff
changeset
|
1065 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
|
1066 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
|
1067 ``@verbose=0`` query using PUT. To include protected properties |
| 5854 | 1068 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
|
1069 ``@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
|
1070 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
|
1071 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1072 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
|
1073 ``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
|
1074 ``@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
|
1075 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
|
1076 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
|
1077 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
|
1078 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
|
1079 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
|
1080 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
|
1081 @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
|
1082 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
|
1083 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
|
1084 currently discouraged. |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1085 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1086 An example of returned values:: |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1087 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1088 { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1089 "data": { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1090 "type": "issue", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1091 "@etag": "\"f15e6942f00a41960de45f9413684591\"", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1092 "link": "https://.../rest/data/issue/23", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1093 "attributes": { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1094 "keyword": [], |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1095 "messages": [ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1096 { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1097 "link": "https://.../rest/data/msg/375", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1098 "id": "375" |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1099 }, |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1100 { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1101 "link": "https://.../rest/data/msg/376", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1102 "id": "376" |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1103 }, |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1104 ... |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1105 ], |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1106 "files": [], |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1107 "status": { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1108 "link": "https://.../rest/data/status/2", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1109 "id": "2" |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1110 }, |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1111 "title": "This is a title title", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1112 "superseder": [], |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1113 "nosy": [ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1114 { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1115 "link": "https://.../rest/data/user/4", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1116 "id": "4" |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1117 }, |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1118 { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1119 "link": "https://.../rest/data/user/5", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1120 "id": "5" |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1121 } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1122 ], |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1123 "assignedto": null, |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1124 }, |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1125 "id": "23" |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1126 } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1127 } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1128 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1129 Retrieve item using key value |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
1130 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1131 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1132 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
|
1133 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
|
1134 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1135 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
|
1136 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
|
1137 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
|
1138 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
|
1139 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
|
1140 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
|
1141 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
|
1142 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
|
1143 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
|
1144 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1145 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
|
1146 ``/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
|
1147 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
|
1148 |
|
5928
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1149 Dealing with Messages and Files |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
1150 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
5928
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1151 |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1152 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
|
1153 |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1154 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
|
1155 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
|
1156 |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1157 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
|
1158 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
|
1159 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
|
1160 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
|
1161 |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1162 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
|
1163 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
|
1164 parameters, e.g.:: |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1165 |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1166 # 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
|
1167 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
|
1168 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
|
1169 fname = 'a-bigger-testfile' |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1170 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
|
1171 c = dict (content = content) |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1172 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
|
1173 |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1174 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
|
1175 |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1176 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
|
1177 -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
|
1178 -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
|
1179 -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
|
1180 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
|
1181 |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1182 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
|
1183 return something like:: |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1184 |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1185 { |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1186 "data": { |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1187 "id": "12", |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1188 "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
|
1189 } |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1190 } |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1191 |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1192 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1193 Other Supported Methods for Items |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
1194 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1195 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1196 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
|
1197 ``/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
|
1198 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
|
1199 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
|
1200 example:: |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1201 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1202 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
|
1203 --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
|
1204 --header 'X-Requested-With: rest' \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1205 --header "Content-Type: application/json" \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1206 --header "Accept: application/json" \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1207 --header 'If-Match: "dd41f02d6f8b4c34b439fc712b522fb3"' \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1208 --data '{ "nosy": [ "1", "5" ] }' \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1209 "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
|
1210 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1211 { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1212 "data": { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1213 "attribute": { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1214 "nosy": [ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1215 "1", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1216 "5" |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1217 ] |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1218 }, |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1219 "type": "issue", |
|
6764
32f52d14b496
Typo fixes, formatting fixes, jwt -> JWT, add link to JWT issue
John Rouillard <rouilj@ieee.org>
parents:
6681
diff
changeset
|
1220 "link": "https://example.com/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
|
1221 "id": "23" |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1222 } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1223 } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1224 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1225 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
|
1226 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1227 --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
|
1228 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1229 this is returned:: |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1230 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1231 { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1232 "data": { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1233 "attribute": { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1234 "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
|
1235 }, |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1236 "type": "issue", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1237 "link": |
|
5928
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1238 "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
|
1239 "id": "23" |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1240 } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1241 } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1242 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1243 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
|
1244 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
|
1245 Changing both nosy and title:: |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1246 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1247 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
|
1248 --header 'Referer: https://.../' \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1249 --header 'X-Requested-With: rest' \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1250 --header "Content-Type: application/json" \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1251 --header "Accept: application/json" \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1252 --header 'If-Match: "8209add59a79713d64f4d1a072aef740"' \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1253 --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
|
1254 "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
|
1255 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1256 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
|
1257 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1258 { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1259 "data": { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1260 "attribute": { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1261 "title": "This is now my new title", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1262 "nosy": [ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1263 "4", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1264 "5" |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1265 ] |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1266 }, |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1267 "type": "issue", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1268 "link": |
|
5928
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1269 "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
|
1270 "id": "23" |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1271 } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1272 } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1273 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1274 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
|
1275 work. So using:: |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1276 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1277 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
|
1278 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1279 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
|
1280 payload:: |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1281 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1282 curl -u admin:admin ... |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1283 --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
|
1284 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1285 produces:: |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1286 |
|
5892
afb5705d1fe5
Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
5888
diff
changeset
|
1287 {"data": {"attribute": {...}, "type": "issue", |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1288 "link": "https://...", "id": "23"}} |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1289 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1290 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
|
1291 line. |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1292 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1293 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
|
1294 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
|
1295 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
|
1296 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
|
1297 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
|
1298 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1299 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
|
1300 ``/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
|
1301 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
|
1302 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
|
1303 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
|
1304 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
|
1305 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
|
1306 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
|
1307 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
|
1308 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
|
1309 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
|
1310 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
|
1311 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
|
1312 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1313 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
|
1314 --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
|
1315 --header "Accept: application/json" \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1316 --header 'If-Match: "c6e2d81019acff1da7a2da45f93939bd"' \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1317 --data-urlencode '@op=add' \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1318 --data 'nosy=3' \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1319 "https://.../rest/data/issue/23" |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1320 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1321 which returns:: |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1322 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1323 { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1324 "data": { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1325 "attribute": { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1326 "nosy": [ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1327 "3", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1328 "4" |
|
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 }, |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1331 "type": "issue", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1332 "link": "https://.../rest/data/issue/23", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1333 "id": "23" |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1334 } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1335 } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1336 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1337 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
|
1338 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
|
1339 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1340 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
|
1341 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
|
1342 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
|
1343 ``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
|
1344 ``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
|
1345 ``@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
|
1346 ``If-Match`` header. |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1347 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1348 /data/\ *class*/\ *id*/\ *property* field |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
1349 ----------------------------------------- |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1350 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1351 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
|
1352 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
|
1353 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
|
1354 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1355 For example:: |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1356 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1357 { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1358 "data": { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1359 "link": "https://.../rest/data/issue/22/title", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1360 "data": "I need Broken PC", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1361 "type": "<class 'str'>", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1362 "id": "22", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1363 "@etag": "\"370510512b2d8fc3f98aac3d762cc7b1\"" |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1364 } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1365 } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1366 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1367 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1368 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
|
1369 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
|
1370 |
|
5928
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1371 Message and File Content |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
1372 ~~~~~~~~~~~~~~~~~~~~~~~~ |
|
5928
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 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
|
1375 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
|
1376 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
|
1377 |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1378 { |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1379 "data": { |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1380 "id": "11", |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1381 "type": "<class 'str'>", |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1382 "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
|
1383 "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
|
1384 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
|
1385 "@etag": "\"584f82231079e349031bbb853747df1c\"" |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1386 } |
|
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 |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1389 (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
|
1390 |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1391 .. _binary_content property: |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1392 |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1393 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
|
1394 binary_content |
|
5930
cc6891ea1f01
issue2551067 make url into liternal not clickble.
John Rouillard <rouilj@ieee.org>
parents:
5929
diff
changeset
|
1395 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
|
1396 returns:: |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1397 |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1398 { |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1399 "data": { |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1400 "id": "11", |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1401 "type": "<class 'bytes'>", |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1402 "link": "https://.../demo/rest/data/file/11/binary_content", |
|
5929
0368d75de544
issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents:
5928
diff
changeset
|
1403 "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
|
1404 "@etag": "\"74276f75ef71a30a0cce62dc6a8aa1bb\"" |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1405 } |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1406 } |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1407 |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1408 (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
|
1409 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
|
1410 Content`_. |
|
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1411 |
|
5929
0368d75de544
issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents:
5928
diff
changeset
|
1412 The data is a json encoded hexidecimal representation of the data. |
|
0368d75de544
issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents:
5928
diff
changeset
|
1413 |
|
5928
fa661043fc5b
issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents:
5901
diff
changeset
|
1414 |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1415 Other Supported Methods for fields |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
1416 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1417 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1418 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
|
1419 ``/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
|
1420 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
|
1421 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
|
1422 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
|
1423 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1424 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
|
1425 --header "Accept: application/json" \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1426 --data "data=Provisional" \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1427 --header "If-Match: 079eba599152f3eed00567e23258fecf" \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1428 --data-urlencode "@etag=079eba599152f3eed00567e23258fecf" \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1429 "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
|
1430 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1431 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
|
1432 type:: |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1433 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1434 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
|
1435 --header "Accept: application/json" \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1436 --header 'Content-Type: application/json' \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1437 --header "Referer: https://.../" \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1438 --header "x-requested-with: rest" \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1439 --header 'If-Match: "e2e6cc43c3475a4a3d9e5343617c11c3"' \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1440 --data '{"leadtime": "2d" }' \ |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1441 "https://.../rest/data/issue/10" |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1442 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1443 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
|
1444 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
|
1445 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
|
1446 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
|
1447 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1448 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
|
1449 ``/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
|
1450 ``@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
|
1451 ``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
|
1452 which is the same as performing a PUT on the field url. ``add`` and |
| 5854 | 1453 ``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
|
1454 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
|
1455 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
|
1456 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
|
1457 method. |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1458 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1459 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
|
1460 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
|
1461 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
|
1462 ``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
|
1463 ``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
|
1464 ``@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
|
1465 ``If-Match`` header. |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1466 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1467 Tunneling Methods via POST |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
1468 -------------------------- |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1469 |
| 7455 | 1470 If you are working through a proxy and unable to use http methods like |
| 1471 PUT, PATCH, or DELETE, you can use POST to perform the action. To tunnel | |
| 5854 | 1472 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
|
1473 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
|
1474 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
|
1475 without tunneling. |
|
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 Examples and Use Cases |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
1478 ====================== |
|
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 sample python client |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
1481 -------------------- |
|
5723
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 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
|
1484 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
|
1485 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1486 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1487 >>> import requests |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1488 >>> 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
|
1489 >>> s = requests.session() |
|
5933
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1490 >>> session.auth = ('admin', 'admin') |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1491 >>> 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
|
1492 >>> if r.status_code != 200: |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1493 ... 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
|
1494 ... exit(1) |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1495 >>> print (r.json() ['data']['data'] |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1496 TEST Title |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1497 >>> 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
|
1498 >>> 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
|
1499 >>> 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
|
1500 ... 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
|
1501 ... exit(1) |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1502 >>> print(r.json()) |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1503 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1504 Retire/Restore:: |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1505 >>> 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
|
1506 >>> print (r.json()) |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1507 >>> 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
|
1508 >>> etag = r.headers['ETag'] |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1509 >>> print("ETag: %s" % etag) |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1510 >>> etag = r.json()['data']['@etag'] |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1511 >>> print("@etag: %s" % etag) |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1512 >>> h = {'If-Match': etag, |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1513 ... 'X-Requested-With': 'rest', |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1514 ... '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
|
1515 >>> 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
|
1516 >>> 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
|
1517 >>> print(r.json()) |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1518 >>> 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
|
1519 >>> 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
|
1520 >>> print(r.json()) |
|
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 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
|
1523 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
|
1524 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
|
1525 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
|
1526 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
|
1527 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
|
1528 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
|
1529 |
| 6204 | 1530 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
|
1531 |
|
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1532 curl -s -u admin:admin \ |
|
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1533 -H "Referer: https://tracker.example.com/demo/" \ |
|
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1534 -H "X-requested-with: rest" \ |
|
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1535 -H "Content-Type: application/json" \ |
|
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1536 https://tracker.example.com/demo/rest/data/status/1 |
|
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1537 |
|
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1538 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
|
1539 for this retire example:: |
|
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1540 |
|
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1541 curl -s -u admin:admin \ |
|
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1542 -H "Referer: https://tracker.example.com/demo/" \ |
|
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1543 -H "X-requested-with: rest" \ |
|
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1544 -H "Content-Type: application/json" \ |
|
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1545 -H 'If-Match: "a502faf4d6b8e3897c4ecd66b5597571"' \ |
|
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1546 --data-raw '{ "@op":"action", "@action_name": "retire" }'\ |
|
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1547 -X PATCH \ |
|
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1548 https://tracker.example.com/demo/rest/data/status/1 |
|
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1549 |
|
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1550 and restore:: |
|
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1551 |
|
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1552 curl -s -u admin:admin \ |
|
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1553 -H "Referer: https://tracker.example.com/demo/" \ |
|
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1554 -H "X-requested-with: rest" \ |
|
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1555 -H "Content-Type: application/json" \ |
|
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1556 -H 'If-Match: "a502faf4d6b8e3897c4ecd66b5597571"' \ |
|
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1557 --data-raw '{ "@op":"action", "@action_name": "restore" }'\ |
|
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1558 -X PATCH \ |
|
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1559 https://tracker.example.com/demo/rest/data/status/1 |
|
0bac8b9a0ecc
Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents:
5930
diff
changeset
|
1560 |
|
5695
3e1b66c4e1e2
Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents:
5688
diff
changeset
|
1561 |
|
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
|
1562 Searches and selection |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
1563 ---------------------- |
|
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
|
1564 |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
1565 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
|
1566 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
|
1567 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
|
1568 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
|
1569 |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
1570 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
|
1571 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
|
1572 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
|
1573 |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
1574 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
|
1575 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
|
1576 |
|
5695
3e1b66c4e1e2
Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents:
5688
diff
changeset
|
1577 $('#superseder').selectize({ |
|
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
|
1578 valueField: 'id', |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
1579 labelField: 'title', |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
1580 searchField: 'title', ... |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
1581 load: function(query, callback) { |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
1582 if (!query.length) return callback(); |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
1583 $.ajax({ |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
1584 url: '.../rest/data/issue?@verbose=2&title=' |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
1585 + encodeURIComponent(query), |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
1586 type: 'GET', |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
1587 error: function() {callback();}, |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
1588 success: function(res) { |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
1589 callback(res.data.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
|
1590 |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
1591 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
|
1592 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
|
1593 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
|
1594 |
|
5695
3e1b66c4e1e2
Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents:
5688
diff
changeset
|
1595 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
|
1596 |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
1597 { |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
1598 "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
|
1599 "@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
|
1600 "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
|
1601 { |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
1602 "link": ".../rest/data/issue/8", |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
1603 "id": "8", |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
1604 "title": "Request for Power plugs" |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
1605 }, |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
1606 { |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
1607 "link": ".../rest/data/issue/27", |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
1608 "id": "27", |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
1609 "title": "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
|
1610 }, |
|
5695
3e1b66c4e1e2
Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents:
5688
diff
changeset
|
1611 ... |
|
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
|
1612 |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
1613 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
|
1614 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
|
1615 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
|
1616 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
|
1617 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
|
1618 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
|
1619 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
|
1620 |
|
5695
3e1b66c4e1e2
Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents:
5688
diff
changeset
|
1621 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
|
1622 |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
1623 .../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
|
1624 |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
1625 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
|
1626 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
|
1627 |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1628 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
|
1629 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
|
1630 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
|
1631 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
|
1632 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
|
1633 |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1634 { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1635 "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
|
1636 "title": "Request for Broken PC", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1637 "id": "1001", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1638 "status": { |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1639 "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
|
1640 "id": "6", |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1641 "name": "resolved" |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1642 } |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
1643 } |
|
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
|
1644 |
|
5695
3e1b66c4e1e2
Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents:
5688
diff
changeset
|
1645 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
|
1646 |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
1647 === 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
|
1648 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
|
1649 === 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
|
1650 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
|
1651 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
|
1652 |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
1653 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
|
1654 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
|
1655 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1656 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1657 Programming the REST API |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
1658 ======================== |
|
5710
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1659 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1660 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
|
1661 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
|
1662 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
|
1663 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1664 Adding new rest endpoints |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
1665 ------------------------- |
|
5710
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1666 |
|
6765
b4bfbd768bc1
How to add dicttoxml at system or tracker level.
John Rouillard <rouilj@ieee.org>
parents:
6764
diff
changeset
|
1667 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
|
1668 directory. |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1669 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1670 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
|
1671 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1672 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
|
1673 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
|
1674 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1675 class RestfulInstance: |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1676 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1677 @Routing.route("/summary2") |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1678 @_data_decorator |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1679 def summary2(self, input): |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1680 result = { "hello": "world" } |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1681 return 200, result |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1682 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1683 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
|
1684 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1685 $ 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
|
1686 { |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1687 "data": { |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1688 "hello": "world" |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1689 } |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1690 } |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1691 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1692 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
|
1693 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1694 # 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
|
1695 @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
|
1696 def get_element_schema(self, class_name, input): |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1697 result = { "schema": {} } |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1698 uid = self.db.getuid () |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1699 if not self.db.security.hasPermission('View', uid, class_name) : |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1700 raise Unauthorised('Permission to view %s denied' % class_name) |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1701 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1702 class_obj = self.db.getclass(class_name) |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1703 props = class_obj.getprops(protected=False) |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1704 schema = result['schema'] |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1705 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1706 for prop in props: |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1707 schema[prop] = { "type": repr(class_obj.properties[prop]) } |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1708 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1709 return result |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1710 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1711 .. |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1712 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
|
1713 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1714 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
|
1715 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1716 $ curl -X GET .../rest/data/issue/@schema |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1717 { |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1718 "schema": { |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1719 "keyword": { |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1720 "type": "<roundup.hyperdb.Multilink to \"keyword\">" |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1721 }, |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1722 "title": { |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1723 "type": "<roundup.hyperdb.String>" |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1724 }, |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1725 "files": { |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1726 "type": "<roundup.hyperdb.Multilink to \"file\">" |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1727 }, |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1728 "status": { |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1729 "type": "<roundup.hyperdb.Link to \"status\">" |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1730 }, ... |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1731 } |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1732 } |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1733 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1734 |
|
0b79bfcb3312
Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents:
5698
diff
changeset
|
1735 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
|
1736 ``/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
|
1737 |
|
5883
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1738 Redefine/move rest endpoints |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
1739 ---------------------------- |
|
5883
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1740 |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1741 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
|
1742 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
|
1743 |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1744 @Routing.route("/summary") |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1745 @_data_decorator |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1746 def summary2(self, input): |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1747 result = { "hello": "world" } |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1748 return 200, result |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1749 |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1750 will return:: |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1751 |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1752 { |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1753 "data": { |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1754 "hello": "world" |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1755 } |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1756 } |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1757 |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1758 |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1759 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
|
1760 endpoints to new locations. Adding:: |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1761 |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1762 @Routing.route("/data2/<:classname>") |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1763 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
|
1764 """ 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
|
1765 |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1766 Existing function is decorated with: |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1767 |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1768 @Routing.route("/data/<:classname>") |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1769 @_data_decorator |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1770 |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1771 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
|
1772 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
|
1773 """ |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1774 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
|
1775 |
| 5886 | 1776 will make the response at /rest/data2/<class> be the same as what is |
| 1777 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
|
1778 |
|
da417bab5cb8
Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents:
5879
diff
changeset
|
1779 |
|
5843
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1780 Controlling Access to Backend Data |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
1781 ---------------------------------- |
|
5843
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1782 |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1783 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
|
1784 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
|
1785 seen. |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1786 |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1787 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
|
1788 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
|
1789 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
|
1790 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
|
1791 your schema to implement `Restricting the list of |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
1792 users that are assignable to a task <customizing.html#restricting-the-list-of-users-that-are-assignable-to-a-task>`__ |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
1793 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
|
1794 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
|
1795 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
|
1796 permission. |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1797 |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1798 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
|
1799 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
|
1800 can't see the roles. Building on the `Adding new rest endpoints`_ |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1801 section this code adds a new endpoint `/data/@permission/Developer` |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1802 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
|
1803 |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1804 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
|
1805 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
|
1806 |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1807 class RestfulInstance(object): |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1808 |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1809 @Routing.route("/data/@permission/Developer") |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1810 def get_role_Developer(self, input): |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1811 '''An endpoint to return a list of users with Developer |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1812 role who can be assigned to an issue. |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1813 |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1814 It ignores attempt to search by any property except |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1815 username and realname. It also ignores the whole @fields |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1816 specification if it specifies a property the user |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1817 can't view. Other @ query params (e.g. @page... and |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1818 @verbose) are supported. |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1819 |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1820 It assumes admin access rights so that the roles property |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1821 of the user can be searched. This is needed if the roles |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1822 property is not searchable/viewable by normal users. A user |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1823 who can search roles can identify users with the admin |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1824 role. So it does not respond the same as a rest/data/users |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1825 search by a non-admin user. |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1826 ''' |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1827 # get real user id |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1828 realuid=self.db.getuid() |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1829 |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1830 def allowed_field(fs): |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1831 if fs.name in ['username', 'realname' ]: |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1832 # only allow search matches for these fields |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1833 return True |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1834 elif fs.name in [ '@fields' ]: |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1835 for prop in fs.value.split(','): |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1836 # if any property is unviewable to user, remove |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1837 # @field entry. If they can't see it for the admin |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1838 # user, don't let them see it for any user. |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1839 if not self.db.security.hasPermission( |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1840 'View', realuid, 'user', property=prop, |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1841 itemid='1'): |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1842 return False |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1843 return True |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1844 elif fs.name.startswith("@"): |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1845 # allow @page..., @verbose etc. |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1846 return True |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1847 |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1848 # deny all other url parmeters |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1849 return False |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1850 |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1851 # Cleanup input.list to prevent user from probing roles |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1852 # or viewing things the user should not be able to view. |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1853 input.list[:] = [ fs for fs in input.list |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1854 if allowed_field(fs) ] |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1855 |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1856 # Add the role filter required to implement the permission |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1857 # search |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1858 input.list.append(MiniFieldStorage("roles", "Developer")) |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1859 |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1860 # change user to acquire permission to search roles |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1861 self.db.setCurrentUser('admin') |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1862 |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1863 # Once we have cleaned up the request, pass it to |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1864 # get_collection as though /rest/data/users?... has been called |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1865 # to get @verbose and other args supported. |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1866 return self.get_collection('user', input) |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1867 |
|
5895
93bbe5340d5b
More typo fixes and verbatim blocks.
John Rouillard <rouilj@ieee.org>
parents:
5894
diff
changeset
|
1868 Calling this with:: |
|
93bbe5340d5b
More typo fixes and verbatim blocks.
John Rouillard <rouilj@ieee.org>
parents:
5894
diff
changeset
|
1869 |
|
93bbe5340d5b
More typo fixes and verbatim blocks.
John Rouillard <rouilj@ieee.org>
parents:
5894
diff
changeset
|
1870 curl 'http://example.com/demo/rest/data/@permission/Developer?@fields=realname&roles=Users&@verbose=2' |
|
93bbe5340d5b
More typo fixes and verbatim blocks.
John Rouillard <rouilj@ieee.org>
parents:
5894
diff
changeset
|
1871 |
|
5843
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1872 produces output similar to:: |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1873 |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1874 { |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1875 "data": { |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1876 "collection": [ |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1877 { |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1878 "username": "agent", |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1879 "link": http://example.com/demo/rest/data/user/4", |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1880 "realname": "James Bond", |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1881 "id": "4" |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1882 } |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1883 ], |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1884 "@total_size": 1 |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1885 } |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1886 } |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1887 |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1888 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
|
1889 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
|
1890 ignored. |
|
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
1891 |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
1892 Changing Access Roles with JSON Web Tokens |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
1893 ------------------------------------------ |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
1894 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
1895 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
|
1896 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
|
1897 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
|
1898 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
|
1899 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
|
1900 issue. |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
1901 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
1902 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
|
1903 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
|
1904 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
|
1905 |
| 6165 | 1906 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
|
1907 you and have access to create a roundup timelog entry (see |
| 7353 | 1908 `<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
|
1909 to the associated issue. This should happen without sharing passwords |
| 6166 | 1910 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
|
1911 ``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
|
1912 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
1913 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
|
1914 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
|
1915 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
1916 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
|
1917 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
1918 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
|
1919 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
|
1920 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
|
1921 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
|
1922 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
|
1923 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
|
1924 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
|
1925 random characters of data. (You will get a message |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
1926 ``Support for jwt disabled by admin.`` if it's not long enough.) |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
1927 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
|
1928 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
|
1929 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
1930 Create role |
|
5898
be8524335bfa
Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents:
5896
diff
changeset
|
1931 ~~~~~~~~~~~ |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
1932 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
1933 Adding this snippet of code to the tracker's ``schema.py`` should create a role with the |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
1934 proper authorization:: |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
1935 |
|
5892
afb5705d1fe5
Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
5888
diff
changeset
|
1936 db.security.addRole(name="User:timelog", |
|
afb5705d1fe5
Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
5888
diff
changeset
|
1937 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
|
1938 |
|
afb5705d1fe5
Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
5888
diff
changeset
|
1939 db.security.addPermissionToRole('User:timelog', 'Rest Access') |
|
afb5705d1fe5
Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
5888
diff
changeset
|
1940 |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
1941 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
|
1942 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
|
1943 db.security.addPermissionToRole("User:timelog", perm) |
|
5892
afb5705d1fe5
Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
5888
diff
changeset
|
1944 |
|
afb5705d1fe5
Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
5888
diff
changeset
|
1945 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
|
1946 properties=('id', 'times'), |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
1947 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
|
1948 props_only=False) |
|
5892
afb5705d1fe5
Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
5888
diff
changeset
|
1949 db.security.addPermissionToRole("User:timelog", perm) |
|
afb5705d1fe5
Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
5888
diff
changeset
|
1950 |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
1951 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
|
1952 properties=('id', 'times'), |
|
5893
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
1953 description="Allow editing timelog for issue", |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
1954 props_only=False) |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
1955 db.security.addPermissionToRole("User:timelog", perm) |
|
5892
afb5705d1fe5
Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
5888
diff
changeset
|
1956 |
|
afb5705d1fe5
Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
5888
diff
changeset
|
1957 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
|
1958 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
|
1959 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
|
1960 role has the User role. |
|
afb5705d1fe5
Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
5888
diff
changeset
|
1961 |
|
afb5705d1fe5
Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
5888
diff
changeset
|
1962 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
|
1963 the issue. The etag is passed in the ``If-Match`` HTTP header when you |
| 5894 | 1964 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
|
1965 |
|
5892
afb5705d1fe5
Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
5888
diff
changeset
|
1966 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
|
1967 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
|
1968 ``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
|
1969 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
|
1970 value, and replace the ``times`` value. |
|
afb5705d1fe5
Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
5888
diff
changeset
|
1971 |
|
afb5705d1fe5
Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
5888
diff
changeset
|
1972 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
|
1973 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
|
1974 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
|
1975 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
1976 Create rest endpoints |
|
5898
be8524335bfa
Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents:
5896
diff
changeset
|
1977 ~~~~~~~~~~~~~~~~~~~~~ |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
1978 |
|
5892
afb5705d1fe5
Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents:
5888
diff
changeset
|
1979 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
|
1980 only been tested with python3):: |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
1981 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
1982 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
|
1983 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
1984 class RestfulInstance(object): |
|
5893
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
1985 @Routing.route("/jwt/issue", 'POST') |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
1986 @_data_decorator |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
1987 def generate_jwt(self, input): |
|
6519
22cf6ee7ad88
jwt issue example: require input data, lowercase roles
John Rouillard <rouilj@ieee.org>
parents:
6384
diff
changeset
|
1988 """Create a JSON Web Token (jwt) |
|
22cf6ee7ad88
jwt issue example: require input data, lowercase roles
John Rouillard <rouilj@ieee.org>
parents:
6384
diff
changeset
|
1989 """ |
|
5893
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
1990 import jwt |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
1991 import datetime |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
1992 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
|
1993 |
|
5893
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
1994 # 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
|
1995 # 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
|
1996 # 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
|
1997 # 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
|
1998 |
|
5893
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
1999 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
|
2000 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
|
2001 try: |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2002 auth = self.client.env['HTTP_AUTHORIZATION'] |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2003 scheme, challenge = auth.split(' ', 1) |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2004 except (ValueError, AttributeError): |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2005 # bad format for header |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2006 raise Unauthorised(denialmsg) |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2007 if scheme.lower() != 'basic': |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2008 raise Unauthorised(denialmsg) |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2009 else: |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2010 raise Unauthorised(denialmsg) |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2011 |
|
6519
22cf6ee7ad88
jwt issue example: require input data, lowercase roles
John Rouillard <rouilj@ieee.org>
parents:
6384
diff
changeset
|
2012 # verify we have input data. |
|
22cf6ee7ad88
jwt issue example: require input data, lowercase roles
John Rouillard <rouilj@ieee.org>
parents:
6384
diff
changeset
|
2013 if not input: |
|
22cf6ee7ad88
jwt issue example: require input data, lowercase roles
John Rouillard <rouilj@ieee.org>
parents:
6384
diff
changeset
|
2014 raise UsageError("Missing data payload. " |
|
22cf6ee7ad88
jwt issue example: require input data, lowercase roles
John Rouillard <rouilj@ieee.org>
parents:
6384
diff
changeset
|
2015 "Verify Content-Type is sent") |
|
22cf6ee7ad88
jwt issue example: require input data, lowercase roles
John Rouillard <rouilj@ieee.org>
parents:
6384
diff
changeset
|
2016 |
|
5893
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2017 # 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
|
2018 # 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
|
2019 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
|
2020 rolenames = [] |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2021 for role in all_roles: |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2022 rolenames.append(role[0]) |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2023 |
|
5893
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2024 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
|
2025 |
|
5893
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2026 claim= { 'sub': self.db.getuid(), |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2027 'iss': self.db.config.TRACKER_WEB, |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2028 'aud': self.db.config.TRACKER_WEB, |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2029 'iat': datetime.datetime.utcnow(), |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2030 } |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2031 |
|
5893
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2032 lifetime = 0 |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2033 if 'lifetime' in input: |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2034 if input['lifetime'].value != 'unlimited': |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2035 try: |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2036 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
|
2037 except ValueError: |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2038 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
|
2039 " 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
|
2040 else: |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2041 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
|
2042 |
|
5893
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2043 if lifetime: # if lifetime = 0 make unlimited by omitting exp claim |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2044 claim['exp'] = datetime.datetime.utcnow() + lifetime |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2045 |
|
5893
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2046 newroles = [] |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2047 if 'roles' in input: |
|
6519
22cf6ee7ad88
jwt issue example: require input data, lowercase roles
John Rouillard <rouilj@ieee.org>
parents:
6384
diff
changeset
|
2048 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
|
2049 if role not in rolenames: |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2050 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
|
2051 if role in user_roles: |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2052 newroles.append(role) |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2053 continue |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2054 parentrole = role.split(':', 1)[0] |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2055 if parentrole in user_roles: |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2056 newroles.append(role) |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2057 continue |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2058 |
|
5893
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2059 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
|
2060 |
|
5893
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2061 claim['roles'] = newroles |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2062 else: |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2063 claim['roles'] = user_roles |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2064 secret = self.db.config.WEB_JWT_SECRET |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2065 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
|
2066 |
|
6315
84655a4223c6
Update doc for jwt example to omit b2s() if pyjwt version >= 2.0.0
John Rouillard <rouilj@ieee.org>
parents:
6311
diff
changeset
|
2067 # if jwt.__version__ >= 2.0.0 jwt.encode() returns string |
|
84655a4223c6
Update doc for jwt example to omit b2s() if pyjwt version >= 2.0.0
John Rouillard <rouilj@ieee.org>
parents:
6311
diff
changeset
|
2068 # 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
|
2069 result = {"jwt": b2s(myjwt), |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2070 } |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2071 |
|
5893
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2072 return 200, result |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2073 |
|
5893
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2074 @Routing.route("/jwt/validate", 'GET') |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2075 @_data_decorator |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2076 def validate_jwt(self,input): |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2077 import jwt |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2078 if not 'jwt' in input: |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2079 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
|
2080 |
|
5893
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2081 myjwt = input['jwt'].value |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2082 |
|
5893
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2083 secret = self.db.config.WEB_JWT_SECRET |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2084 try: |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2085 result = jwt.decode(myjwt, secret, |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2086 algorithms=['HS256'], |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2087 audience=self.db.config.TRACKER_WEB, |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2088 issuer=self.db.config.TRACKER_WEB, |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2089 ) |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2090 except jwt.exceptions.InvalidTokenError as err: |
|
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2091 return 401, str(err) |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2092 |
|
5893
13f5ac918120
fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents:
5892
diff
changeset
|
2093 return 200, result |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2094 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2095 **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
|
2096 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
|
2097 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
|
2098 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
|
2099 username/password authentication. |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2100 |
|
6764
32f52d14b496
Typo fixes, formatting fixes, jwt -> JWT, add link to JWT issue
John Rouillard <rouilj@ieee.org>
parents:
6681
diff
changeset
|
2101 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
|
2102 providing patches to existing code to: |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2103 |
|
7361
bc6bcffbed2a
rewrite JWT future to use refresh tokens.
John Rouillard <rouilj@ieee.org>
parents:
7353
diff
changeset
|
2104 1. create long lived refresh tokens |
|
bc6bcffbed2a
rewrite JWT future to use refresh tokens.
John Rouillard <rouilj@ieee.org>
parents:
7353
diff
changeset
|
2105 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
|
2106 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
|
2107 ignored by the roundup core |
|
bc6bcffbed2a
rewrite JWT future to use refresh tokens.
John Rouillard <rouilj@ieee.org>
parents:
7353
diff
changeset
|
2108 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
|
2109 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
|
2110 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2111 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
|
2112 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2113 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
|
2114 -H "X-requested-with: rest" \ |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2115 -H "Content-Type: application/json" \ |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2116 --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
|
2117 https://.../demo/rest/JWT/issue |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2118 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2119 (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
|
2120 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2121 { |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2122 "data": { |
|
6764
32f52d14b496
Typo fixes, formatting fixes, jwt -> JWT, add link to JWT issue
John Rouillard <rouilj@ieee.org>
parents:
6681
diff
changeset
|
2123 "JWT": "eyJ0eXAiOiJK......XxMDb-Q3oCnMpyhxPXMAk" |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2124 } |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2125 } |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2126 |
|
6764
32f52d14b496
Typo fixes, formatting fixes, jwt -> JWT, add link to JWT issue
John Rouillard <rouilj@ieee.org>
parents:
6681
diff
changeset
|
2127 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
|
2128 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
|
2129 |
|
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 curl -s -H "Referer: https://.../demo/" \ |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2132 -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
|
2133 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
|
2134 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2135 (note no login is required) which returns:: |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2136 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2137 { |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2138 "data": { |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2139 "user": "3", |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2140 "roles": [ |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2141 "user:timelog" |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2142 ], |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2143 "iss": "https://.../demo/", |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2144 "aud": "https://.../demo/", |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2145 "iat": 1569542404, |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2146 "exp": 1569546004 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2147 } |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2148 } |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2149 |
|
6764
32f52d14b496
Typo fixes, formatting fixes, jwt -> JWT, add link to JWT issue
John Rouillard <rouilj@ieee.org>
parents:
6681
diff
changeset
|
2150 |
|
32f52d14b496
Typo fixes, formatting fixes, jwt -> JWT, add link to JWT issue
John Rouillard <rouilj@ieee.org>
parents:
6681
diff
changeset
|
2151 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
|
2152 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
|
2153 |
|
32f52d14b496
Typo fixes, formatting fixes, jwt -> JWT, add link to JWT issue
John Rouillard <rouilj@ieee.org>
parents:
6681
diff
changeset
|
2154 .. _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
|
2155 |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2156 Final steps |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
2157 ~~~~~~~~~~~ |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2158 |
| 5887 | 2159 See the `upgrading directions`_ on how to use the ``updateconfig`` |
| 5888 | 2160 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
|
2161 roundup-admin. Then set the ``JWT_secret`` to at least 32 characters |
| 5887 | 2162 (more is better up to 512 bits). |
|
5878
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2163 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2164 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
|
2165 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
|
2166 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
|
2167 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
|
2168 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
|
2169 https://issues.roundup-tracker.org/.) |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2170 |
|
1b57d8f3eb97
Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents:
5865
diff
changeset
|
2171 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
|
2172 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
|
2173 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
|
2174 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
|
2175 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
|
2176 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
|
2177 |
|
5843
da1f40b5148d
issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents:
5826
diff
changeset
|
2178 |
|
5737
07d8bbf6ee5f
Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents:
5723
diff
changeset
|
2179 Creating Custom Rate Limits |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
2180 --------------------------- |
|
5737
07d8bbf6ee5f
Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents:
5723
diff
changeset
|
2181 |
|
5738
9777d7311bc0
Clean up the custom rate limit doc.
John Rouillard <rouilj@ieee.org>
parents:
5737
diff
changeset
|
2182 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
|
2183 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
|
2184 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
|
2185 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
|
2186 |
|
9777d7311bc0
Clean up the custom rate limit doc.
John Rouillard <rouilj@ieee.org>
parents:
5737
diff
changeset
|
2187 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
|
2188 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
|
2189 ``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
|
2190 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
|
2191 |
|
07d8bbf6ee5f
Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents:
5723
diff
changeset
|
2192 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
|
2193 from datetime import timedelta |
|
07d8bbf6ee5f
Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents:
5723
diff
changeset
|
2194 |
|
07d8bbf6ee5f
Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents:
5723
diff
changeset
|
2195 def grl(self): |
|
07d8bbf6ee5f
Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents:
5723
diff
changeset
|
2196 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
|
2197 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
|
2198 |
|
07d8bbf6ee5f
Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents:
5723
diff
changeset
|
2199 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
|
2200 |
|
07d8bbf6ee5f
Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents:
5723
diff
changeset
|
2201 uid = self.db.getuid() |
|
07d8bbf6ee5f
Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents:
5723
diff
changeset
|
2202 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
|
2203 node = class_obj.getnode(uid) |
|
07d8bbf6ee5f
Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents:
5723
diff
changeset
|
2204 |
|
07d8bbf6ee5f
Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents:
5723
diff
changeset
|
2205 # set value to 0 to use WEB_API_CALLS_PER_INTERVAL |
|
07d8bbf6ee5f
Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents:
5723
diff
changeset
|
2206 user_calls = node.__getattr__('rate_limit_calls') |
|
07d8bbf6ee5f
Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents:
5723
diff
changeset
|
2207 # set to 0 to use WEB_API_INTERVAL_IN_SEC |
|
07d8bbf6ee5f
Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents:
5723
diff
changeset
|
2208 user_interval = node.__getattr__('rate_limit_interval') |
|
07d8bbf6ee5f
Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents:
5723
diff
changeset
|
2209 |
|
07d8bbf6ee5f
Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents:
5723
diff
changeset
|
2210 return RateLimit(user_calls or calls, |
|
07d8bbf6ee5f
Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents:
5723
diff
changeset
|
2211 timedelta(seconds=(user_interval or interval))) |
|
07d8bbf6ee5f
Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents:
5723
diff
changeset
|
2212 else: |
|
07d8bbf6ee5f
Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents:
5723
diff
changeset
|
2213 # 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
|
2214 return None |
|
07d8bbf6ee5f
Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents:
5723
diff
changeset
|
2215 |
|
07d8bbf6ee5f
Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents:
5723
diff
changeset
|
2216 RestfulInstance.getRateLimit = grl |
|
07d8bbf6ee5f
Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents:
5723
diff
changeset
|
2217 |
|
5738
9777d7311bc0
Clean up the custom rate limit doc.
John Rouillard <rouilj@ieee.org>
parents:
5737
diff
changeset
|
2218 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
|
2219 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
|
2220 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
|
2221 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
|
2222 |
|
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
2223 Test Examples |
|
7473
f8b5b0310f88
I think headings are consistant now.
John Rouillard <rouilj@ieee.org>
parents:
7455
diff
changeset
|
2224 ~~~~~~~~~~~~~ |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
2225 |
|
5895
93bbe5340d5b
More typo fixes and verbatim blocks.
John Rouillard <rouilj@ieee.org>
parents:
5894
diff
changeset
|
2226 Rate limit tests:: |
|
5723
59a3bbd3603a
Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents:
5710
diff
changeset
|
2227 |
|
6765
b4bfbd768bc1
How to add dicttoxml at system or tracker level.
John Rouillard <rouilj@ieee.org>
parents:
6764
diff
changeset
|
2228 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
|
2229 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
|
2230 |
|
b4bfbd768bc1
How to add dicttoxml at system or tracker level.
John Rouillard <rouilj@ieee.org>
parents:
6764
diff
changeset
|
2231 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
|
2232 for the user identified by password. |
