Mercurial > p > roundup > code

annotate doc/rest.txt @ 6185:1cb2375015f0

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Enable timing stats reporting in REST interface.
author John Rouillard <rouilj@ieee.org>
date Wed, 03 Jun 2020 00:52:32 -0400
parents acb9841bb4fd
children 0f0dedd2f95d
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6167
81ae33038ec5 more index entries.
John Rouillard <rouilj@ieee.org>
parents: 6166
diff changeset
1 .. index:: pair: api; Representational state transfer
81ae33038ec5 more index entries.
John Rouillard <rouilj@ieee.org>
parents: 6166
diff changeset
2 pair: api; rest
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
3
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
4 ====================
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
5 REST API for Roundup
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
6 ====================
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
7
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
8 .. contents::
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
9 :local:
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
10 :depth: 3
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
11
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
12 Introduction
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
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
15 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
16 Google Summer of Code (GSOC) by Chau Nguyen, supervised by Ezio
5879
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5878
diff changeset
17 Melotti was integrated. The code was updated by Ralf Schlatterbeck
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5878
diff changeset
18 and John Rouillard to fix some shortcomings and provide the necessary
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
19 functions for a single page web application, e.g. etag support,
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
20 pagination, field embedding among others.
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
21
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
22 Enabling the REST API
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
23 ---------------------
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
24
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
25 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
26 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
27
5879
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5878
diff changeset
28 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
29 "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
30 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
31
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5878
diff changeset
32 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
33
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5878
diff changeset
34 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
35 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
36
5901
a592e3156134 Added more verbage on "Rest Access" permission and reworked search docs.
John Rouillard <rouilj@ieee.org>
parents: 5898
diff changeset
37 You could also create a new role "rest" and assign the "Rest Access"
a592e3156134 Added more verbage on "Rest Access" permission and reworked search docs.
John Rouillard <rouilj@ieee.org>
parents: 5898
diff changeset
38 permission to that role and then just add the "rest" permissions to
a592e3156134 Added more verbage on "Rest Access" permission and reworked search docs.
John Rouillard <rouilj@ieee.org>
parents: 5898
diff changeset
39 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
40
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
41 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
42 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
43 /rest removed for brevity.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
44
5826
8e17c34a5cf0 issue2551048. Document WEB_SECRET_KEY in config.ini.
John Rouillard <rouilj@ieee.org>
parents: 5824
diff changeset
45 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
46 ``[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
47 `upgrading directions`_ using ``roundup-admin ... updateconfig
8e17c34a5cf0 issue2551048. Document WEB_SECRET_KEY in config.ini.
John Rouillard <rouilj@ieee.org>
parents: 5824
diff changeset
48 ...`` 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
49 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
50 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
51 ``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
52
8e17c34a5cf0 issue2551048. Document WEB_SECRET_KEY in config.ini.
John Rouillard <rouilj@ieee.org>
parents: 5824
diff changeset
53 If ``secret_key`` is not set, the etag value returned by a REST
8e17c34a5cf0 issue2551048. Document WEB_SECRET_KEY in config.ini.
John Rouillard <rouilj@ieee.org>
parents: 5824
diff changeset
54 call will be change on every call even though the item has not
8e17c34a5cf0 issue2551048. Document WEB_SECRET_KEY in config.ini.
John Rouillard <rouilj@ieee.org>
parents: 5824
diff changeset
55 changed.
8e17c34a5cf0 issue2551048. Document WEB_SECRET_KEY in config.ini.
John Rouillard <rouilj@ieee.org>
parents: 5824
diff changeset
56
8e17c34a5cf0 issue2551048. Document WEB_SECRET_KEY in config.ini.
John Rouillard <rouilj@ieee.org>
parents: 5824
diff changeset
57 .. _upgrading directions: upgrading.html
8e17c34a5cf0 issue2551048. Document WEB_SECRET_KEY in config.ini.
John Rouillard <rouilj@ieee.org>
parents: 5824
diff changeset
58
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
59 Preventing CSRF Attacks
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
60 =======================
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
61
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
62 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
63 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
64 = yes`` or ``required``.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
65
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
66 Rate Limiting the API
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
67 =====================
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
68
5896
a8df94ec8040 Rate Limit is available in this code.
John Rouillard <rouilj@ieee.org>
parents: 5895
diff changeset
69 This is a work in progress. This version of roundup includes Rate
a8df94ec8040 Rate Limit is available in this code.
John Rouillard <rouilj@ieee.org>
parents: 5895
diff changeset
70 Limiting for the API (which is different from rate limiting login
a8df94ec8040 Rate Limit is available in this code.
John Rouillard <rouilj@ieee.org>
parents: 5895
diff changeset
71 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
72
5896
a8df94ec8040 Rate Limit is available in this code.
John Rouillard <rouilj@ieee.org>
parents: 5895
diff changeset
73 It is enabled by setting the ``api_calls_per_interval`` and
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
74 ``api_interval_in_sec`` configuration parameters in the ``[web]``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
75 section of ``config.ini``. The settings are documented in the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
76 config.ini file.
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
77
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
78 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
79 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
80 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
81 ``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
82 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
83 additional call every 10 seconds. ``api_calls_per_interval`` is the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
84 burst rate that you are willing to allow within `api_interval_in_sec``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
85 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
86 ``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
87 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
88 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
89 60/sec and 3600/sec.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
90
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
91 A single page app may make 20 or 30 calls to populate the page (e.g. a
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
92 list of open issues). Then wait a few seconds for the user to select
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
93 an issue. When displaying the issue, it needs another 20 or calls to
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
94 populate status dropdowns, pull the first 10 messages in the issue
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
95 etc. Controlling the burst rate as well as the average rate is a
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
96 tuning exercise left for the tracker admin.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
97
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
98 Also the rate limit is a little lossy. Under heavy load, it is
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
99 possible for it to miscount allowing more than burst count. Errors of
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
100 up to 10% have been seen on slower hardware.
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
101
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
102 Client API
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
103 ----------
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
104
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
105 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
106 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
107 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
108 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
109
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
110 Headers
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
111 =======
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
112
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
113 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
114
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
115 **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
116
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
117 **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
118
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
119 **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
120 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
121 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
122
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
123 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
124 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
125
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
126 **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
127
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
128 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
129
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
130 **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
131
6182
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
132 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
133
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
134 **Sunset**: an http date after which the end point will not be available.
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
135
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
136 will be returned. It should be used as a hint that the REST endpoint
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
137 will be going away. See https://tools.ietf.org/html/rfc8594 for
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
138 details on this header and the sunset link type.
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
139
6185
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
140 Hyperdb Stats
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
141 =============
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
142
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
143 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
144 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
145 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
146 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
147 like::
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
148
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
149 { "data": {
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
150 ...
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
151 "@stats": {
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
152 "cache_hits": 3,
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
153 "cache_misses": 1,
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
154 "get_items": 0.0009722709655761719,
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
155 "filtering": 0,
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
156 "elapsed": 0.04731464385986328
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
157 }
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
158 }
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
159 }
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
160
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
161 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
162 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
163 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
164 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
165 info.
1cb2375015f0 Enable timing stats reporting in REST interface.
John Rouillard <rouilj@ieee.org>
parents: 6182
diff changeset
166
6182
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
167 Versioning
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
168 ==========
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
169
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
170 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
171 integers. The current version is ``1``. Version selection is
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
172 implemented in the server using one of three methods:
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
173
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
174 1. Explicit version param in accept header:
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
175 ``application/json; version=1``
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
176
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
177 2. Version suffix in vendor accept header:
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
178 ``application/vnd.json.test-v1+json``
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
179
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
180 3. Adding version specifier in query string: ``@apiver=1``
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
181
acb9841bb4fd Adding description of Sunset header and versioning
John Rouillard <rouilj@ieee.org>
parents: 6167
diff changeset
182 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
183 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
184 described above.
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
185
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
186 General Guidelines
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
187 ==================
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
188
5854
d5aed7106ee6 Need to fix spelling.
John Rouillard <rouilj@ieee.org>
parents: 5843
diff changeset
189 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
190 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
191 ``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
192 ``If-Match`` header or an ``"@etag`` property in the data payload if
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
193 the method supports a payload.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
194
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
195 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
196 ``@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
197 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
198
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
199 The default return format is JSON. If you add the ``dicttoxml.py``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
200 module you can request XML formatted data using the header ``Accept:
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
201 application/xml`` in your request. Both output formats are similar in
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
202 structure.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
203
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
204 All output is wrapped in an envelope called ``data``.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
205
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
206 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
207 ``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
208 well as a ``collections`` list of objects::
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
209
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
210 { "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
211 "meta data field1": "value",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
212 "meta data field2": "value",
5854
d5aed7106ee6 Need to fix spelling.
John Rouillard <rouilj@ieee.org>
parents: 5843
diff changeset
213 "collection": [
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
214 { "link": "url to item",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
215 "id": "internal identifier for item" },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
216 { "link": "url to second item",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
217 "id": "id item 2" },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
218 ... ]
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
219 "@links": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
220 "relation": [
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
221 { "rel": "relation/subrelation",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
222 "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
223 ...
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
224 ],
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
225 "relation2": [ {...} ], ...
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
226 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
227 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
228 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
229
5854
d5aed7106ee6 Need to fix spelling.
John Rouillard <rouilj@ieee.org>
parents: 5843
diff changeset
230 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
231 collections endpoint.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
232
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
233 The ``link`` fields implement HATEOS by supplying a url for the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
234 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
235 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
236
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
237 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
238 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
239 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
240 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
241 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
242 represented.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
243
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
244 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
245 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
246 ``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
247 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
248 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
249 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
250 conflicts with the self url.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
251
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
252 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
253 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
254 ``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
255 the issue. Example::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
256
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
257 { "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
258 "meta data field1": "value",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
259 "type": "type of item, issue, user ..."
5854
d5aed7106ee6 Need to fix spelling.
John Rouillard <rouilj@ieee.org>
parents: 5843
diff changeset
260 "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
261 "attributes": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
262 "title": "title of issue",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
263 "nosy": [
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
264 { "link": "url for user4",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
265 "id": "4" }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
266 ],
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
267
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
268 ... }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
269 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
270 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
271
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
272 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
273 ``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
274 the property. This ``data`` subfield may be a simple string (all types
5854
d5aed7106ee6 Need to fix spelling.
John Rouillard <rouilj@ieee.org>
parents: 5843
diff changeset
275 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
276 properties). Example::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
277
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
278 { "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
279 "type": "description of class",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
280 "@etag": "\"f15e6942f00a41960de45f9413684591\"",
5854
d5aed7106ee6 Need to fix spelling.
John Rouillard <rouilj@ieee.org>
parents: 5843
diff changeset
281 "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
282 "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
283 "data": "value of property"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
284 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
285 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
286
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
287
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
288 Special Endpoints
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
289 =================
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
290
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
291 There are a few special endpoints that provide some additional data.
5854
d5aed7106ee6 Need to fix spelling.
John Rouillard <rouilj@ieee.org>
parents: 5843
diff changeset
292 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
293 "Programming the REST API"_ below.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
294
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
295 /summary
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
296 ^^^^^^^^
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
297
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
298 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
299 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
300 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
301
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
302 /data
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
303 ^^^^^
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
304
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
305 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
306
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
307 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
308 classes can be reached via ``/data/<classname>`` where ``<classname>``
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
309 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
310 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
311 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
312 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
313 ``/data/issue/42/title``.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
314
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
315
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
316 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
317 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
318 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
319
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
320 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
321
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
322 /data/\ *class* Collection
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
323 ==========================
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
324
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
325 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
326 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
327 ``@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
328 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
329 https://.../rest/data/issue returns::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
330
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
331 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
332 "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
333 "collection": [
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
334 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
335 "id": "1",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
336 "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
337 },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
338 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
339 "id": "100",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
340 "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
341 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
342 ...
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
343 ],
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
344 "@total_size": 171
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
345 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
346 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
347
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
348 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
349 sections.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
350
5982
88316ac61ab0 Add warning about collection size limit as anti-DOS mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5933
diff changeset
351 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
352 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
353 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
354 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
355 details.
88316ac61ab0 Add warning about collection size limit as anti-DOS mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5933
diff changeset
356
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
357 Searching
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
358 ^^^^^^^^^
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 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
361 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
362
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
363 .. list-table:: Query Parameters Examples
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
364 :header-rows: 1
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
365 :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
366
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
367 * - Query parameter
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
368 - Field type
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
369 - Explanation
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
370 * - ``title=foo``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
371 - String
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
372 - 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
373 in the title.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
374 * - ``status=2``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
375 - Link
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
376 - 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
377 * - ``status=open``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
378 - Link
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
379 - find any issue where the name of the status is open.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
380 Note this is not a string match so using nosy=ope will fail.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
381 * - ``nosy=1``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
382 - MultiLink
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
383 - 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
384 * - ``nosy=admin``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
385 - MultiLink
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
386 - 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
387 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
388 * - ``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
389 values match false.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
390 - Boolean
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
391 - 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
392
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
393 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
394 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
395 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
396 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
397 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
398 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
399
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
400 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
401 performs a case-insensitive substring search. Searching for
5898
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
402 ``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
403 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
404
a592e3156134 Added more verbage on "Rest Access" permission and reworked search docs.
John Rouillard <rouilj@ieee.org>
parents: 5898
diff changeset
405 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
406 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
407 with a capital ``S``. Another example is:
5898
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
408 ``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
409 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
410 ``%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
411 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
412 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
413 ``that`` in the title.
5723
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 To make this clear, searching
5898
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
416 ``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
417 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
418 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
419 ``name`` using ``https://.../rest/data/keyword?name=Foo`` (note
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
420 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
421 ``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
422
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
423 In all cases the field ``@total_size`` is reported which is the total
5854
d5aed7106ee6 Need to fix spelling.
John Rouillard <rouilj@ieee.org>
parents: 5843
diff changeset
424 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
425
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
426 Other data types: Date, Interval Integer, Number need examples and may
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
427 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
428 body of a msg) is a work in progress.
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
429
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
430 .. _URL Encoding: https://en.wikipedia.org/wiki/Percent-encoding
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
431
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
432 Transitive Searching
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
433 ~~~~~~~~~~~~~~~~~~~~
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
434
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
435 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
436 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
437 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
438 (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
439 using: ``/issues?messages.author=admin``. Note that this requires
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
440 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
441 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
442 present, the search will silently drop the attribute.
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
443
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
444 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
445 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
446 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
447 ``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
448 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
449
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
450 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
451 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
452 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
453 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
454
5865
04deafac71ab Implement sorting of collections in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5863
diff changeset
455 Sorting
04deafac71ab Implement sorting of collections in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5863
diff changeset
456 ^^^^^^^
04deafac71ab Implement sorting of collections in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5863
diff changeset
457
04deafac71ab Implement sorting of collections in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5863
diff changeset
458 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
459 ``@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
460 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
461 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
462 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
463 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
464 and then by id of an issue::
04deafac71ab Implement sorting of collections in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5863
diff changeset
465
04deafac71ab Implement sorting of collections in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5863
diff changeset
466 @sort=status,-id
04deafac71ab Implement sorting of collections in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5863
diff changeset
467
04deafac71ab Implement sorting of collections in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5863
diff changeset
468
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
469 Pagination
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
470 ^^^^^^^^^^
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
471
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
472 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
473 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
474 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
475
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
476 .. list-table:: Query Parameters Examples
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
477 :header-rows: 1
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
478 :widths: 20 80
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
479
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
480 * - Query parameter
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
481 - Explanation
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
482 * - ``@page_size``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
483 - 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
484 ``@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
485 * - ``@page_index``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
486 - (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
487 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
488
5854
d5aed7106ee6 Need to fix spelling.
John Rouillard <rouilj@ieee.org>
parents: 5843
diff changeset
489 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
490 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
491
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
492 { "data":
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 "collection": { ... },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
495 "@total_size": 222,
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
496 "@links": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
497 "self": [
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
498 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
499 "uri":
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
500 "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
501 "rel": "self"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
502 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
503 ],
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
504 "next": [
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 "uri":
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
507 "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
508 "rel": "next"
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 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
512 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
513 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
514
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
515 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
516 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
517 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
518 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
519 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
520 (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
521 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
522
5982
88316ac61ab0 Add warning about collection size limit as anti-DOS mechanism.
John Rouillard <rouilj@ieee.org>
parents: 5933
diff changeset
523 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
524 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
525 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
526 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
527
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
528 Field embedding and verbose output
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
529 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
530
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
531 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
532 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
533 ``@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
534 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
535
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
536 .. list-table:: Query Parameters Examples
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
537 :header-rows: 1
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
538 :widths: 20 80
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
539
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
540 * - Query parameter
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
541 - Explanation
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
542 * - ``@verbose=0``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
543 - each item in the collection has its "id" property displayed
5854
d5aed7106ee6 Need to fix spelling.
John Rouillard <rouilj@ieee.org>
parents: 5843
diff changeset
544 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
545 * - ``@verbose=1``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
546 - 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
547 is the default.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
548 * - ``@verbose=2``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
549 - 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
550 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
551 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
552 * - ``@verbose=3``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
553 - 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
554 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
555 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
556 * - ``@fields=status,title``
5824
352e78c3b4ab Allow @fields to include protected properties, document @protected
John Rouillard <rouilj@ieee.org>
parents: 5738
diff changeset
557 - 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
558 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
559 @verbose parameter. Protected properties
352e78c3b4ab Allow @fields to include protected properties, document @protected
John Rouillard <rouilj@ieee.org>
parents: 5738
diff changeset
560 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
561
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
562 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
563 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
564 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
565 ``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
566 for an issue is its title.
e097ff5064b8 Allow transitive properties in @fields in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5982
diff changeset
567 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
568 ``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
569 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
570 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
571 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
572 ``@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
573 ``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
574
6090
e097ff5064b8 Allow transitive properties in @fields in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5982
diff changeset
575
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
576 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
577 "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
578 "collection": [
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
579 {
6090
e097ff5064b8 Allow transitive properties in @fields in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5982
diff changeset
580 "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
581 "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
582 "id": "1",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
583 "status": {
6090
e097ff5064b8 Allow transitive properties in @fields in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5982
diff changeset
584 "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
585 "id": "1",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
586 "name": "new"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
587 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
588 },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
589 ...
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
590 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
591
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
592 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
593 ``@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
594 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
595
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
596 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
597 "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
598 "collection": [
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
599 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
600 "link":
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
601 "https://.../rest/data/issue/1",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
602 "id": "1",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
603 "status": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
604 "link":
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
605 "https://.../rest/data/status/1",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
606 "id": "1"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
607 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
608 },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
609 ...
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
610 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
611
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
612 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
613 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
614 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
615 output.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
616
5854
d5aed7106ee6 Need to fix spelling.
John Rouillard <rouilj@ieee.org>
parents: 5843
diff changeset
617 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
618 items in the collection.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
619
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
620 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
621 by these features.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
622
5928
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
623 Getting Message and Files Content
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
624 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
625
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
626 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
627 ``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
628
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
629 {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
630 "data": {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
631 "id": "11",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
632 "type": "msg",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
633 "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
634 "attributes": {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
635 "author": {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
636 "id": "5",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
637 "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
638 },
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
639 "content": {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
640 "link": "https://.../demo/msg11/"
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
641 },
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
642 "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
643 "files": [],
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
644 "inreplyto": null,
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
645 "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
646 "messagetype": {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
647 "id": "1",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
648 "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
649 },
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
650 "recipients": [
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
651 {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
652 "id": "1",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
653 "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
654 },
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
655 {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
656 "id": "3",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
657 "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
658 },
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
659 {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
660 "id": "4",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
661 "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
662 }
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
663 ],
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
664 "subject": null,
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
665 "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
666 },
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
667 "@etag": "\"584f82231079e349031bbb853747df1c\""
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
668 }
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
669 }
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
670
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
671 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
672 ``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
673 /, 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
674 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
675
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
676 Also you can use the url:
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
677
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
678 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
679 like::
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
680
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
681 ...
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
682 "author": {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
683 "id": "5",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
684 "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
685 },
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
686 "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
687 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
688 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
689 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
690 "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
691 ...
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
692
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
693 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
694 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
695
5929
0368d75de544 issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents: 5928
diff changeset
696 Retrieving the contents of a file is similar. Performing a
0368d75de544 issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents: 5928
diff changeset
697 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
698
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
699 {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
700 "data": {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
701 "id": "11",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
702 "type": "file",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
703 "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
704 "attributes": {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
705 "acl": null,
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
706 "content": {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
707 "link": "https://.../demo/file11/"
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
708 },
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
709 "name": "afile",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
710 "status": {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
711 "id": "1",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
712 "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
713 },
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
714 "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
715 },
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
716 "@etag": "\"74276f75ef71a30a0cce62dc6a8aa1bb\""
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
717 }
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
718 }
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
719
5929
0368d75de544 issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents: 5928
diff changeset
720 To download the file contents for this example you would
0368d75de544 issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents: 5928
diff changeset
721 perform an http GET using: ``https://.../demo/file11/``. The trailing
0368d75de544 issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents: 5928
diff changeset
722 / 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
723 application/octet-stream.
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
724
5929
0368d75de544 issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents: 5928
diff changeset
725 If you perform a get on
0368d75de544 issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents: 5928
diff changeset
726 ``https://.../demo/rest/data/file/11?@verbose=3`` the content field
0368d75de544 issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents: 5928
diff changeset
727 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
728
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
729 "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
730 property. mdsum: bd990c0f8833dd991daf610b81b62316",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
731
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
732
5929
0368d75de544 issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents: 5928
diff changeset
733 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
734 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
735
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
736 Other query params
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
737 ^^^^^^^^^^^^^^^^^^
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
738
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
739 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
740
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
741 .. list-table:: Query Parameters Examples
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
742 :header-rows: 1
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
743 :widths: 20 80
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
744
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
745 * - Query parameter
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
746 - Explanation
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
747 * - ``@pretty=false``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
748 - 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
749 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
750 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
751 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
752 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
753 this time.
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 Using the POST method
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
756 ^^^^^^^^^^^^^^^^^^^^^
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
757
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
758 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
759 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
760 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
761 parameters as the GET method after successful creation.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
762
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
763 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
764 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
765
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
766
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
767 Safely Re-sending POST
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
768 ^^^^^^^^^^^^^^^^^^^^^^
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
769
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
770 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
771 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
772 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
773 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
774
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
775 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
776 Once Exactly spec:
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
777 https://tools.ietf.org/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
778
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
779 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
780 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
781
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
782 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
783
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
784 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
785 -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
786 -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
787 --data '' \
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
788 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
789
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
790 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
791
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
792 {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
793 "data": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
794 "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
795 "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
796 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
797 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
798
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
799 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
800 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
801 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
802
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
803 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
804 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
805 ``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
806
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
807 For example::
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
808
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
809 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
810 -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
811 -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
812 -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
813 --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
814 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
815
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
816 returns::
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
817
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
818 {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
819 "data": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
820 "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
821 "id": "2280"
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
822 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
823 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
824
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
825 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
826 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
827 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
828
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
829 Note that POE links are by restricted to the class that was used to
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
830 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
831 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
832 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
833
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
834 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
835 -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
836 --data 'lifetime=100&generic=1' \
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
837 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
838
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
839 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
840
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
841 {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
842 "data": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
843 "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
844 "link":
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
845 "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
846 }
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
847 }
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
848
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
849 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
850 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
851 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
852
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
853 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
854 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
855 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
856
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
857 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
858
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
859 * 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
860 * 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
861 * 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
862 fails
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
863
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
864 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
865 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
866 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
867 mechanism.
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
868
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
869 .. [#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
870 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
871 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
872 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
873 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
874 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
875 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
876 response was lost.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
877
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
878 Other Supported Methods for Collections
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
879 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
880
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
881 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
882 allowed on a given endpoint.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
883
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
884 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
885
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
886 /data/\ *class*/\ *id* item
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
887 ===========================
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
888
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
889 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
890 (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
891 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
892 (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
893 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
894
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
895 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
896 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
897 account used for the query.
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 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
900 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
901 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
902 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
903 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
904 transitive properties. By default protected
5892
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
905 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
906 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
907 ``@verbose=0`` query using PUT. To include protected properties
5854
d5aed7106ee6 Need to fix spelling.
John Rouillard <rouilj@ieee.org>
parents: 5843
diff changeset
908 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
909 ``@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
910 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
911
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
912 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
913 ``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
914 ``@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
915 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
916 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
917 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
918 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
919 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
920 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
921 @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
922 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
923 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
924 currently discouraged.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
925
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
926 An example of returned values::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
927
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
928 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
929 "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
930 "type": "issue",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
931 "@etag": "\"f15e6942f00a41960de45f9413684591\"",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
932 "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
933 "attributes": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
934 "keyword": [],
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
935 "messages": [
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
936 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
937 "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
938 "id": "375"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
939 },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
940 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
941 "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
942 "id": "376"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
943 },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
944 ...
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
945 ],
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
946 "files": [],
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
947 "status": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
948 "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
949 "id": "2"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
950 },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
951 "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
952 "superseder": [],
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
953 "nosy": [
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
954 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
955 "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
956 "id": "4"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
957 },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
958 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
959 "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
960 "id": "5"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
961 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
962 ],
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
963 "assignedto": null,
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
964 },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
965 "id": "23"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
966 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
967 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
968
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
969 Retrieve item using key value
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
970 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
971
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
972 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
973 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
974
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
975 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
976 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
977 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
978 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
979 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
980 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
981 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
982 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
983 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
984
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
985 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
986 ``/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
987 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
988
5928
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
989 Dealing with Messages and Files
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
990 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
991
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
992 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
993
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
994 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
995 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
996
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
997 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
998 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
999 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
1000 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
1001
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1002 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
1003 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
1004 parameters, e.g.::
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1005
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1006 # 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
1007 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
1008 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
1009 fname = 'a-bigger-testfile'
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1010 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
1011 c = dict (content = content)
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1012 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
1013
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1014 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
1015
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1016 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
1017 -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
1018 -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
1019 -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
1020 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
1021
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1022 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
1023 return something like::
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1024
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1025 {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1026 "data": {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1027 "id": "12",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1028 "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
1029 }
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1030 }
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1031
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1032
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1033 Other Supported Methods for Items
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1034 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1035
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1036 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
1037 ``/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
1038 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
1039 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
1040 example::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1041
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1042 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
1043 --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
1044 --header 'X-Requested-With: rest' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1045 --header "Content-Type: application/json" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1046 --header "Accept: application/json" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1047 --header 'If-Match: "dd41f02d6f8b4c34b439fc712b522fb3"' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1048 --data '{ "nosy": [ "1", "5" ] }' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1049 "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
1050
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1051 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1052 "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1053 "attribute": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1054 "nosy": [
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1055 "1",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1056 "5"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1057 ]
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 "type": "issue",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1060 "link":
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1061 "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
1062 "id": "23"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1063 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1064 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1065
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1066 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
1067
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1068 --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
1069
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1070 this is returned::
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 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1073 "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1074 "attribute": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1075 "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
1076 },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1077 "type": "issue",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1078 "link":
5928
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1079 "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
1080 "id": "23"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1081 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1082 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1083
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1084 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
1085 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
1086 Changing both nosy and title::
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 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
1089 --header 'Referer: https://.../' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1090 --header 'X-Requested-With: rest' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1091 --header "Content-Type: application/json" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1092 --header "Accept: application/json" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1093 --header 'If-Match: "8209add59a79713d64f4d1a072aef740"' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1094 --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
1095 "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
1096
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1097 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
1098
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 "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1101 "attribute": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1102 "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
1103 "nosy": [
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1104 "4",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1105 "5"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1106 ]
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1107 },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1108 "type": "issue",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1109 "link":
5928
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1110 "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
1111 "id": "23"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1112 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1113 }
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 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
1116 work. So using::
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 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
1119
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1120 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
1121 payload::
5723
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 curl -u admin:admin ...
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1124 --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
1125
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1126 produces::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1127
5892
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
1128 {"data": {"attribute": {...}, "type": "issue",
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1129 "link": "https://...", "id": "23"}}
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1130
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1131 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
1132 line.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1133
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1134 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
1135 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
1136 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
1137 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
1138 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
1139
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1140 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
1141 ``/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
1142 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
1143 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
1144 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
1145 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
1146 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
1147 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
1148 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
1149 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
1150 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
1151 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
1152 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
1153
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1154 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
1155 --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
1156 --header "Accept: application/json" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1157 --header 'If-Match: "c6e2d81019acff1da7a2da45f93939bd"' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1158 --data-urlencode '@op=add' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1159 --data 'nosy=3' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1160 "https://.../rest/data/issue/23"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1161
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1162 which returns::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1163
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1164 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1165 "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1166 "attribute": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1167 "nosy": [
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1168 "3",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1169 "4"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1170 ]
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1171 },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1172 "type": "issue",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1173 "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
1174 "id": "23"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1175 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1176 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1177
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1178 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
1179 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
1180
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1181 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
1182 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
1183 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
1184 ``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
1185 ``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
1186 ``@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
1187 ``If-Match`` header.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1188
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1189 /data/\ *class*/\ *id*/\ *property* field
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1190 =========================================
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1191
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1192 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
1193 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
1194 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
1195
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1196 For example::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1197
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1198 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1199 "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1200 "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
1201 "data": "I need Broken PC",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1202 "type": "<class 'str'>",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1203 "id": "22",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1204 "@etag": "\"370510512b2d8fc3f98aac3d762cc7b1\""
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1205 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1206 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1207
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1208
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1209 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
1210 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
1211
5928
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1212 Message and File Content
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1213 ^^^^^^^^^^^^^^^^^^^^^^^^
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1214
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1215 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
1216 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
1217 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
1218
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1219 {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1220 "data": {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1221 "id": "11",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1222 "type": "<class 'str'>",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1223 "link": "https://.../demo/rest/data/msg/11/content",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1224 "data": "of has to who pleasure. or of account give because the reprehenderit\neu to quisquam velit, passage, was or...",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1225 "@etag": "\"584f82231079e349031bbb853747df1c\""
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1226 }
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1227 }
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1228
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1229 (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
1230
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1231 .. _binary_content property:
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1232
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1233 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
1234 binary_content
5930
cc6891ea1f01 issue2551067 make url into liternal not clickble.
John Rouillard <rouilj@ieee.org>
parents: 5929
diff changeset
1235 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
1236 returns::
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1237
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1238 {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1239 "data": {
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1240 "id": "11",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1241 "type": "<class 'bytes'>",
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1242 "link": "https://.../demo/rest/data/file/11/binary_content",
5929
0368d75de544 issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents: 5928
diff changeset
1243 "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
1244 "@etag": "\"74276f75ef71a30a0cce62dc6a8aa1bb\""
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1245 }
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1246 }
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1247
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1248 (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
1249 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
1250 Content`_.
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1251
5929
0368d75de544 issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents: 5928
diff changeset
1252 The data is a json encoded hexidecimal representation of the data.
0368d75de544 issue2551067 corrections/cleanup.
John Rouillard <rouilj@ieee.org>
parents: 5928
diff changeset
1253
5928
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1254
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1255 Other Supported Methods for fields
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1256 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1257
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1258 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
1259 ``/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
1260 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
1261 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
1262 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
1263
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1264 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
1265 --header "Accept: application/json" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1266 --data "data=Provisional" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1267 --header "If-Match: 079eba599152f3eed00567e23258fecf" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1268 --data-urlencode "@etag=079eba599152f3eed00567e23258fecf" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1269 "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
1270
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1271 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
1272 type::
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 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
1275 --header "Accept: application/json" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1276 --header 'Content-Type: application/json' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1277 --header "Referer: https://.../" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1278 --header "x-requested-with: rest" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1279 --header 'If-Match: "e2e6cc43c3475a4a3d9e5343617c11c3"' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1280 --data '{"leadtime": "2d" }' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1281 "https://.../rest/data/issue/10"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1282
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1283 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
1284 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
1285 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
1286 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
1287
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1288 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
1289 ``/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
1290 ``@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
1291 ``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
1292 which is the same as performing a PUT on the field url. ``add`` and
5854
d5aed7106ee6 Need to fix spelling.
John Rouillard <rouilj@ieee.org>
parents: 5843
diff changeset
1293 ``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
1294 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
1295 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
1296 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
1297 method.
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 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
1300 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
1301 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
1302 ``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
1303 ``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
1304 ``@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
1305 ``If-Match`` header.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1306
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1307 Tunneling Methods via POST
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1308 ==========================
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1309
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1310 If you are working through a proxy and unable to use http method like
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1311 PUT, PATCH or DELETE you can use POST to perform the action. To tunnel
5854
d5aed7106ee6 Need to fix spelling.
John Rouillard <rouilj@ieee.org>
parents: 5843
diff changeset
1312 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
1313 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
1314 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
1315 without tunneling.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1316
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1317 Examples and Use Cases
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1318 ----------------------
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1319
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1320 sample python client
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1321 ====================
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 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
1324 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
1325
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1326
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1327 >>> import requests
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1328 >>> 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
1329 >>> s = requests.session()
5933
0bac8b9a0ecc Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents: 5930
diff changeset
1330 >>> session.auth = ('admin', 'admin')
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1331 >>> 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
1332 >>> if r.status_code != 200:
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1333 ... 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
1334 ... exit(1)
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1335 >>> print (r.json() ['data']['data']
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1336 TEST Title
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1337 >>> 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
1338 >>> 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
1339 >>> 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
1340 ... 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
1341 ... exit(1)
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1342 >>> print(r.json())
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1343
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1344 Retire/Restore::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1345 >>> 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
1346 >>> print (r.json())
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1347 >>> 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
1348 >>> etag = r.headers['ETag']
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1349 >>> print("ETag: %s" % etag)
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1350 >>> etag = r.json()['data']['@etag']
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1351 >>> print("@etag: %s" % etag)
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1352 >>> h = {'If-Match': etag,
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1353 ... 'X-Requested-With': 'rest',
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1354 ... '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
1355 >>> 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
1356 >>> 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
1357 >>> print(r.json())
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1358 >>> 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
1359 >>> 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
1360 >>> print(r.json())
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1361
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1362 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
1363 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
1364 to add an Origin header if this check is enabled in your tracker's
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1365 config.ini (look for csrf_enforce_header_origin).
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1366
5933
0bac8b9a0ecc Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents: 5930
diff changeset
1367 A similar curl based retire example is to use:
0bac8b9a0ecc Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents: 5930
diff changeset
1368
0bac8b9a0ecc Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents: 5930
diff changeset
1369 curl -s -u admin:admin \
0bac8b9a0ecc Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents: 5930
diff changeset
1370 -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
1371 -H "X-requested-with: rest" \
0bac8b9a0ecc Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents: 5930
diff changeset
1372 -H "Content-Type: application/json" \
0bac8b9a0ecc Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents: 5930
diff changeset
1373 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
1374
0bac8b9a0ecc Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents: 5930
diff changeset
1375 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
1376 for this retire example::
0bac8b9a0ecc Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents: 5930
diff changeset
1377
0bac8b9a0ecc Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents: 5930
diff changeset
1378 curl -s -u admin:admin \
0bac8b9a0ecc Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents: 5930
diff changeset
1379 -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
1380 -H "X-requested-with: rest" \
0bac8b9a0ecc Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents: 5930
diff changeset
1381 -H "Content-Type: application/json" \
0bac8b9a0ecc Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents: 5930
diff changeset
1382 -H 'If-Match: "a502faf4d6b8e3897c4ecd66b5597571"' \
0bac8b9a0ecc Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents: 5930
diff changeset
1383 --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
1384 -X PATCH \
0bac8b9a0ecc Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents: 5930
diff changeset
1385 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
1386
0bac8b9a0ecc Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents: 5930
diff changeset
1387 and restore::
0bac8b9a0ecc Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents: 5930
diff changeset
1388
0bac8b9a0ecc Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents: 5930
diff changeset
1389 curl -s -u admin:admin \
0bac8b9a0ecc Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents: 5930
diff changeset
1390 -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
1391 -H "X-requested-with: rest" \
0bac8b9a0ecc Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents: 5930
diff changeset
1392 -H "Content-Type: application/json" \
0bac8b9a0ecc Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents: 5930
diff changeset
1393 -H 'If-Match: "a502faf4d6b8e3897c4ecd66b5597571"' \
0bac8b9a0ecc Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents: 5930
diff changeset
1394 --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
1395 -X PATCH \
0bac8b9a0ecc Added curl based examples for retire and restore.
John Rouillard <rouilj@ieee.org>
parents: 5930
diff changeset
1396 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
1397
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
1398
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
1399 Searches and selection
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1400 ======================
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1401
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1402 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
1403 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
1404 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
1405 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
1406
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1407 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
1408 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
1409 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
1410
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1411 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
1412 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
1413
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
1414 $('#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
1415 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
1416 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
1417 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
1418 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
1419 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
1420 $.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
1421 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
1422 + 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
1423 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
1424 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
1425 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
1426 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
1427
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1428 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
1429 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
1430 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
1431
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
1432 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
1433
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1434 {
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1435 "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
1436 "@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
1437 "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
1438 {
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1439 "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
1440 "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
1441 "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
1442 },
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1443 {
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1444 "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
1445 "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
1446 "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
1447 },
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
1448 ...
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
1449
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1450 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
1451 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
1452 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
1453 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
1454 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
1455 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
1456 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
1457
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
1458 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
1459
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1460 .../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
1461
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1462 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
1463 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
1464
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1465 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
1466 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
1467 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
1468 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
1469 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
1470
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1471 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1472 "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
1473 "title": "Request for Broken PC",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1474 "id": "1001",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1475 "status": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1476 "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
1477 "id": "6",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1478 "name": "resolved"
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 }
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
1481
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
1482 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
1483
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1484 === 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
1485 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
1486 === 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
1487 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
1488 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
1489
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1490 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
1491 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
1492
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1493
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1494 Programming the REST API
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1495 ------------------------
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1496
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1497 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
1498 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
1499 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
1500
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1501 Adding new rest endpoints
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1502 =========================
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1503
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1504 Add or edit the file interfaces.py at the root of the tracker
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1505 directory.
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1506
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1507 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
1508
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1509 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
1510 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
1511
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1512 class RestfulInstance:
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1513
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1514 @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
1515 @_data_decorator
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1516 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
1517 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
1518 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
1519
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1520 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
1521
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1522 $ 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
1523 {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1524 "data": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1525 "hello": "world"
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1526 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1527 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1528
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1529 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
1530
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1531 # 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
1532 @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
1533 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
1534 result = { "schema": {} }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1535 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
1536 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
1537 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
1538
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1539 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
1540 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
1541 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
1542
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1543 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
1544 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
1545
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1546 return result
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1547
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1548 ..
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1549 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
1550
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1551 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
1552
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1553 $ 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
1554 {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1555 "schema": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1556 "keyword": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1557 "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
1558 },
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1559 "title": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1560 "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
1561 },
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1562 "files": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1563 "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
1564 },
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1565 "status": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1566 "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
1567 }, ...
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1568 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1569 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1570
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1571
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1572 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
1573 ``/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
1574
5883
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1575 Redefine/move rest endpoints
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1576 ============================
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1577
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1578 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
1579 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
1580
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1581 @Routing.route("/summary")
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1582 @_data_decorator
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1583 def summary2(self, input):
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1584 result = { "hello": "world" }
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1585 return 200, result
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1586
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1587 will return::
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1588
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1589 {
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1590 "data": {
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1591 "hello": "world"
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1592 }
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1593 }
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1594
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1595
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1596 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
1597 endpoints to new locations. Adding::
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1598
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1599 @Routing.route("/data2/<:classname>")
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1600 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
1601 """ 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
1602
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1603 Existing function is decorated with:
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1604
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1605 @Routing.route("/data/<:classname>")
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1606 @_data_decorator
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1607
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1608 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
1609 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
1610 """
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1611 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
1612
5886
f4e77d446add Clarify text.
John Rouillard <rouilj@ieee.org>
parents: 5885
diff changeset
1613 will make the response at /rest/data2/<class> be the same as what is
f4e77d446add Clarify text.
John Rouillard <rouilj@ieee.org>
parents: 5885
diff changeset
1614 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
1615
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1616
5843
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1617 Controlling Access to Backend Data
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1618 ==================================
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1619
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1620 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
1621 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
1622 seen.
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1623
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1624 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
1625 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
1626 permissions scheme. For example access to a user's roles should be
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1627 limited to the user (read only) and an admin. If you have customized
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1628 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
1629 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
1630 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
1631 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
1632 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
1633 permission.
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1634
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1635 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
1636 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
1637 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
1638 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
1639 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
1640
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1641 from roundup.rest import Routing, RestfulInstance
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1642 from cgi import MiniFieldStorage
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1643
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1644 class RestfulInstance(object):
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1645
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1646 @Routing.route("/data/@permission/Developer")
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1647 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
1648 '''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
1649 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
1650
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1651 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
1652 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
1653 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
1654 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
1655 @verbose) are supported.
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1656
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1657 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
1658 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
1659 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
1660 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
1661 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
1662 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
1663 '''
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1664 # get real user id
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1665 realuid=self.db.getuid()
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1666
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1667 def allowed_field(fs):
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1668 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
1669 # 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
1670 return True
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1671 elif fs.name in [ '@fields' ]:
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1672 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
1673 # 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
1674 # @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
1675 # 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
1676 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
1677 'View', realuid, 'user', property=prop,
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1678 itemid='1'):
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1679 return False
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1680 return True
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1681 elif fs.name.startswith("@"):
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1682 # allow @page..., @verbose etc.
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1683 return True
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1684
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1685 # deny all other url parmeters
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1686 return False
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1687
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1688 # 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
1689 # 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
1690 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
1691 if allowed_field(fs) ]
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1692
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1693 # 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
1694 # search
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1695 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
1696
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1697 # 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
1698 self.db.setCurrentUser('admin')
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1699
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1700 # 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
1701 # 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
1702 # 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
1703 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
1704
5895
93bbe5340d5b More typo fixes and verbatim blocks.
John Rouillard <rouilj@ieee.org>
parents: 5894
diff changeset
1705 Calling this with::
93bbe5340d5b More typo fixes and verbatim blocks.
John Rouillard <rouilj@ieee.org>
parents: 5894
diff changeset
1706
93bbe5340d5b More typo fixes and verbatim blocks.
John Rouillard <rouilj@ieee.org>
parents: 5894
diff changeset
1707 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
1708
5843
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1709 produces output similar to::
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1710
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1711 {
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1712 "data": {
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1713 "collection": [
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1714 {
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1715 "username": "agent",
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1716 "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
1717 "realname": "James Bond",
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1718 "id": "4"
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1719 }
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1720 ],
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1721 "@total_size": 1
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1722 }
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1723 }
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1724
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1725 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
1726 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
1727 ignored.
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1728
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1729 Changing Access Roles with JSON Web Tokens
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1730 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1731
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1732 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
1733 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
1734 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
1735 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
1736 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
1737 issue.
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1738
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1739 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
1740 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
1741 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
1742
6165
282b611197a1 Typo fix.
John Rouillard <rouilj@ieee.org>
parents: 6090
diff changeset
1743 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
1744 you and have access to create a roundup timelog entry (see
5895
93bbe5340d5b More typo fixes and verbatim blocks.
John Rouillard <rouilj@ieee.org>
parents: 5894
diff changeset
1745 `<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
1746 to the associated issue. This should happen without sharing passwords
6166
7e148e988cde Insert missing word.
John Rouillard <rouilj@ieee.org>
parents: 6165
diff changeset
1747 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
1748 ``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
1749
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1750 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
1751 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
1752
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1753 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
1754
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1755 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
1756 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
1757 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
1758 access to an issues' ``times`` property.
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1759 3. add support for issuing (and validating) jwts to the rest interface.
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1760 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
1761 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
1762 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
1763 ``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
1764 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
1765 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
1766
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1767 Create role
5898
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
1768 ~~~~~~~~~~~
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1769
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1770 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
1771 proper authorization::
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1772
5892
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
1773 db.security.addRole(name="User:timelog",
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
1774 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
1775
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
1776 db.security.addPermissionToRole('User:timelog', 'Rest Access')
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
1777
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1778 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
1779 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
1780 db.security.addPermissionToRole("User:timelog", perm)
5892
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
1781
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
1782 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
1783 properties=('id', 'times'),
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1784 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
1785 props_only=False)
5892
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
1786 db.security.addPermissionToRole("User:timelog", perm)
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
1787
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1788 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
1789 properties=('id', 'times'),
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1790 description="Allow editing timelog for issue",
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1791 props_only=False)
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1792 db.security.addPermissionToRole("User:timelog", perm)
5892
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
1793
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
1794 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
1795 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
1796 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
1797 role has the User role.
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
1798
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
1799 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
1800 the issue. The etag is passed in the ``If-Match`` HTTP header when you
5894
45a104bb127e Fix markup.
John Rouillard <rouilj@ieee.org>
parents: 5893
diff changeset
1801 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
1802
5892
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
1803 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
1804 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
1805 ``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
1806 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
1807 value, and replace the ``times`` value.
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
1808
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
1809 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
1810 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
1811 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
1812
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1813 Create rest endpoints
5898
be8524335bfa Document exact match; Transitive search
John Rouillard <rouilj@ieee.org>
parents: 5896
diff changeset
1814 ~~~~~~~~~~~~~~~~~~~~~
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1815
5892
afb5705d1fe5 Updates to jwt permissions; typo fixes
John Rouillard <rouilj@ieee.org>
parents: 5888
diff changeset
1816 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
1817 only been tested with python3)::
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1818
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1819 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
1820
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1821 class RestfulInstance(object):
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1822 @Routing.route("/jwt/issue", 'POST')
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1823 @_data_decorator
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1824 def generate_jwt(self, input):
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1825 import jwt
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1826 import datetime
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1827 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
1828
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1829 # 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
1830 # 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
1831 # 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
1832 # 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
1833
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1834 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
1835 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
1836 try:
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1837 auth = self.client.env['HTTP_AUTHORIZATION']
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1838 scheme, challenge = auth.split(' ', 1)
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1839 except (ValueError, AttributeError):
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1840 # bad format for header
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1841 raise Unauthorised(denialmsg)
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1842 if scheme.lower() != 'basic':
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1843 raise Unauthorised(denialmsg)
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1844 else:
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1845 raise Unauthorised(denialmsg)
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1846
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1847 # 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
1848 # 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
1849 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
1850 rolenames = []
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1851 for role in all_roles:
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1852 rolenames.append(role[0])
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1853
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1854 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
1855
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1856 claim= { 'sub': self.db.getuid(),
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1857 'iss': self.db.config.TRACKER_WEB,
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1858 'aud': self.db.config.TRACKER_WEB,
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1859 'iat': datetime.datetime.utcnow(),
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1860 }
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1861
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1862 lifetime = 0
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1863 if 'lifetime' in input:
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1864 if input['lifetime'].value != 'unlimited':
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1865 try:
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1866 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
1867 except ValueError:
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1868 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
1869 " 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
1870 else:
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1871 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
1872
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1873 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
1874 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
1875
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1876 newroles = []
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1877 if 'roles' in input:
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1878 for role in input['roles'].value:
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1879 if role not in rolenames:
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1880 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
1881 if role in user_roles:
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1882 newroles.append(role)
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1883 continue
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1884 parentrole = role.split(':', 1)[0]
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1885 if parentrole in user_roles:
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1886 newroles.append(role)
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1887 continue
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1888
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1889 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
1890
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1891 claim['roles'] = newroles
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1892 else:
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1893 claim['roles'] = user_roles
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1894 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
1895 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
1896
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1897 result = {"jwt": b2s(myjwt),
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1898 }
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1899
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1900 return 200, result
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1901
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1902 @Routing.route("/jwt/validate", 'GET')
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1903 @_data_decorator
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1904 def validate_jwt(self,input):
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1905 import jwt
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1906 if not 'jwt' in input:
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1907 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
1908
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1909 myjwt = input['jwt'].value
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1910
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1911 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
1912 try:
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1913 result = jwt.decode(myjwt, secret,
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1914 algorithms=['HS256'],
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1915 audience=self.db.config.TRACKER_WEB,
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1916 issuer=self.db.config.TRACKER_WEB,
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1917 )
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1918 except jwt.exceptions.InvalidTokenError as err:
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1919 return 401, str(err)
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1920
5893
13f5ac918120 fix spacing on example code and typo fix.
John Rouillard <rouilj@ieee.org>
parents: 5892
diff changeset
1921 return 200, result
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1922
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1923 **Note this is sample code. Use at your own risk.** It breaks a few
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1924 rules about jwts (e.g. it allows you to make unlimited lifetime
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1925 jwts). If you subscribe to the concept of jwt refresh tokens, this code
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1926 will have to be changed as it will only generate jwts with
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1927 username/password authentication.
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1928
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1929 Currently use of jwts an experiment. If this appeals to you consider
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1930 providing patches to existing code to:
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1931
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1932 1. record all jwts created by a user
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1933 2. using the record to allow jwts to be revoked and ignored by the
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1934 roundup core
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1935 3. provide a UI page for managing/revoking jwts
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1936 4. provide a rest api for revoking jwts
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1937
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1938 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
1939
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1940 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
1941 -H "X-requested-with: rest" \
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1942 -H "Content-Type: application/json" \
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1943 --data '{"lifetime": "3600", "roles": [ "user:timelog" ] }' \
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1944 https://.../demo/rest/jwt/issue
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1945
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1946 (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
1947
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1948 {
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1949 "data": {
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1950 "jwt": "eyJ0eXAiOiJK......XxMDb-Q3oCnMpyhxPXMAk"
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1951 }
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1952 }
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1953
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1954 The jwt is shortened in the example since it's large. You can validate
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1955 a jwt to see if it's still valid using::
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1956
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1957
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1958 curl -s -H "Referer: https://.../demo/" \
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1959 -H "X-requested-with: rest" \
5928
fa661043fc5b issue2551067 first cut on docs for dealing with files/messages.
John Rouillard <rouilj@ieee.org>
parents: 5901
diff changeset
1960 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
1961
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1962 (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
1963
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1964 {
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1965 "data": {
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1966 "user": "3",
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1967 "roles": [
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1968 "user:timelog"
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1969 ],
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1970 "iss": "https://.../demo/",
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1971 "aud": "https://.../demo/",
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1972 "iat": 1569542404,
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1973 "exp": 1569546004
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1974 }
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
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1977 Final steps
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1978 ^^^^^^^^^^^
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1979
5887
f4db6abf86d9 more typo fixes.
John Rouillard <rouilj@ieee.org>
parents: 5886
diff changeset
1980 See the `upgrading directions`_ on how to use the ``updateconfig``
5888
John Rouillard <rouilj@ieee.org>
parents: 5887
diff changeset
1981 command to generate an updated copy of config.ini using
5887
f4db6abf86d9 more typo fixes.
John Rouillard <rouilj@ieee.org>
parents: 5886
diff changeset
1982 roundup-admin. Then set the ``jwt_secret`` to at least 32 characters
f4db6abf86d9 more typo fixes.
John Rouillard <rouilj@ieee.org>
parents: 5886
diff changeset
1983 (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
1984
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1985 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
1986 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
1987 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
1988 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
1989 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
1990 https://issues.roundup-tracker.org/.)
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1991
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1992 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
1993 call to create a new timelog entry and another call to update the
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1994 issues times property. If you have other ideas on how jwts can be
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1995 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
1996 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
1997 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
1998
5843
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1999
5737
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2000 Creating Custom Rate Limits
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2001 ===========================
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2002
5738
9777d7311bc0 Clean up the custom rate limit doc.
John Rouillard <rouilj@ieee.org>
parents: 5737
diff changeset
2003 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
2004 the tracker's ``config.ini``. You can return different rate
9777d7311bc0 Clean up the custom rate limit doc.
John Rouillard <rouilj@ieee.org>
parents: 5737
diff changeset
2005 limits based on the user, time of day, phase of moon etc.
9777d7311bc0 Clean up the custom rate limit doc.
John Rouillard <rouilj@ieee.org>
parents: 5737
diff changeset
2006
9777d7311bc0 Clean up the custom rate limit doc.
John Rouillard <rouilj@ieee.org>
parents: 5737
diff changeset
2007 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
2008 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
2009 ``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
2010 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
2011
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2012 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
2013 from datetime import timedelta
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2014
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2015 def grl(self):
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2016 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
2017 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
2018
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2019 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
2020
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2021 uid = self.db.getuid()
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2022 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
2023 node = class_obj.getnode(uid)
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2024
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2025 # 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
2026 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
2027 # 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
2028 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
2029
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2030 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
2031 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
2032 else:
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2033 # 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
2034 return None
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2035
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2036 RestfulInstance.getRateLimit = grl
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
2037
5738
9777d7311bc0 Clean up the custom rate limit doc.
John Rouillard <rouilj@ieee.org>
parents: 5737
diff changeset
2038 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
2039 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
2040 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
2041 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
2042
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
2043 Test Examples
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
2044 ^^^^^^^^^^^^^
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
2045
5895
93bbe5340d5b More typo fixes and verbatim blocks.
John Rouillard <rouilj@ieee.org>
parents: 5894
diff changeset
2046 Rate limit tests::
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
2047
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
2048 seq 1 300 | xargs -P 20 -n 1 curl --head -si \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
2049 https://.../rest/data/status/new \# | grep Remaining
Roundup Issue Tracker: http://roundup-tracker.org/