Mercurial > p > roundup > code

annotate doc/rest.txt @ 5883:da417bab5cb8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add more programming rest interface examples. Fix broken link.
author John Rouillard <rouilj@ieee.org>
date Sun, 29 Sep 2019 22:01:09 -0400
parents 94a7669677ae
children 30b76c165ee6
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
1
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
2 ====================
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
3 REST API for Roundup
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
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
6 .. contents::
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
7 :local:
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
8 :depth: 3
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
9
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
10 Introduction
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
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
13 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
14 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
15 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
16 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
17 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
18 pagination, field embedding among others.
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
19
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
20 Enabling the REST API
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
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
23 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
24 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
25
5879
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5878
diff changeset
26 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
27 "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
28 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
29
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5878
diff changeset
30 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
31
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5878
diff changeset
32 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
33 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
34
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
35 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
36 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
37 /rest removed for brevity.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
38
5826
8e17c34a5cf0 issue2551048. Document WEB_SECRET_KEY in config.ini.
John Rouillard <rouilj@ieee.org>
parents: 5824
diff changeset
39 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
40 ``[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
41 `upgrading directions`_ using ``roundup-admin ... updateconfig
8e17c34a5cf0 issue2551048. Document WEB_SECRET_KEY in config.ini.
John Rouillard <rouilj@ieee.org>
parents: 5824
diff changeset
42 ...`` 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
43 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
44 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
45 ``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
46
8e17c34a5cf0 issue2551048. Document WEB_SECRET_KEY in config.ini.
John Rouillard <rouilj@ieee.org>
parents: 5824
diff changeset
47 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
48 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
49 changed.
8e17c34a5cf0 issue2551048. Document WEB_SECRET_KEY in config.ini.
John Rouillard <rouilj@ieee.org>
parents: 5824
diff changeset
50
8e17c34a5cf0 issue2551048. Document WEB_SECRET_KEY in config.ini.
John Rouillard <rouilj@ieee.org>
parents: 5824
diff changeset
51 .. _upgrading directions: upgrading.html
8e17c34a5cf0 issue2551048. Document WEB_SECRET_KEY in config.ini.
John Rouillard <rouilj@ieee.org>
parents: 5824
diff changeset
52
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
53 Preventing CSRF Attacks
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
54 =======================
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
55
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
56 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
57 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
58 = yes`` or ``required``.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
59
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
60 Rate Limiting the API
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
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
63 This is a work in progress. Check the release notes to see if your
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
64 version of roundup includes Rate Limiting for the API (which is
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
65 different from rate limiting login attempts on the web interface).
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
66
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
67 This is enabled by setting the ``api_calls_per_interval`` and
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
68 ``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
69 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
70 config.ini file.
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
71
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
72 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
73 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
74 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
75 ``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
76 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
77 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
78 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
79 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
80 ``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
81 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
82 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
83 60/sec and 3600/sec.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
84
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
85 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
86 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
87 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
88 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
89 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
90 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
91
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
92 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
93 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
94 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
95
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
96 Client API
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
97 ----------
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
98
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
99 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
100 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
101 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
102 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
103
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
104 Headers
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
105 =======
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
106
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
107 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
108
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
109 **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
110
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
111 **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
112
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
113 **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
114 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
115 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
116
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
117 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
118 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
119
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
120 **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
121
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
122 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
123
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
124 **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
125
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
126
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
127 General Guidelines
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
128 ==================
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
129
5854
d5aed7106ee6 Need to fix spelling.
John Rouillard <rouilj@ieee.org>
parents: 5843
diff changeset
130 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
131 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
132 ``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
133 ``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
134 the method supports a payload.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
135
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
136 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
137 ``@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
138 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
139
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
140 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
141 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
142 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
143 structure.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
144
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
145 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
146
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
147 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
148 ``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
149 well as a ``collections`` list of objects::
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
150
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
151 { "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
152 "meta data field1": "value",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
153 "meta data field2": "value",
5854
d5aed7106ee6 Need to fix spelling.
John Rouillard <rouilj@ieee.org>
parents: 5843
diff changeset
154 "collection": [
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
155 { "link": "url to item",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
156 "id": "internal identifier for item" },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
157 { "link": "url to second item",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
158 "id": "id item 2" },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
159 ... ]
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
160 "@links": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
161 "relation": [
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
162 { "rel": "relation/subrelation",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
163 "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
164 ...
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
165 ],
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
166 "relation2": [ {...} ], ...
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
167 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
168 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
169 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
170
5854
d5aed7106ee6 Need to fix spelling.
John Rouillard <rouilj@ieee.org>
parents: 5843
diff changeset
171 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
172 collections endpoint.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
173
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
174 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
175 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
176 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
177
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
178 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
179 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
180 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
181 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
182 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
183 represented.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
184
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
185 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
186 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
187 ``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
188 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
189 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
190 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
191 conflicts with the self url.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
192
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
193 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
194 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
195 ``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
196 the issue. Example::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
197
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
198 { "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
199 "meta data field1": "value",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
200 "type": "type of item, issue, user ..."
5854
d5aed7106ee6 Need to fix spelling.
John Rouillard <rouilj@ieee.org>
parents: 5843
diff changeset
201 "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
202 "attributes": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
203 "title": "title of issue",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
204 "nosy": [
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
205 { "link": "url for user4",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
206 "id": "4" }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
207 ],
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
208
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
209 ... }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
210 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
211 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
212
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
213 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
214 ``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
215 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
216 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
217 properties). Example::
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 { "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
220 "type": "description of class",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
221 "@etag": "\"f15e6942f00a41960de45f9413684591\"",
5854
d5aed7106ee6 Need to fix spelling.
John Rouillard <rouilj@ieee.org>
parents: 5843
diff changeset
222 "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
223 "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
224 "data": "value of property"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
225 }
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 Special Endpoints
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
230 =================
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
231
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
232 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
233 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
234 "Programming the REST API"_ below.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
235
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
236 /summary
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
237 ^^^^^^^^
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
238
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
239 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
240 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
241 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
242
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
243 /data
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
244 ^^^^^
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
245
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
246 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
247
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
248 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
249 classes can be reached via ``/data/<classname>`` where ``<classname>``
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
250 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
251 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
252 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
253 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
254 ``/data/issue/42/title``.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
255
5723
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 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
258 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
259 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
260
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
261 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
262
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
263 /data/\ *class* Collection
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
264 ==========================
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
265
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
266 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
267 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
268 ``@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
269 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
270 https://.../rest/data/issue returns::
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 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
273 "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
274 "collection": [
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
275 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
276 "id": "1",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
277 "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
278 },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
279 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
280 "id": "100",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
281 "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
282 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
283 ...
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 "@total_size": 171
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
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
289 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
290 sections.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
291
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
292 Searching
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
293 ^^^^^^^^^
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 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
296 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
297
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
298 .. list-table:: Query Parameters Examples
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
299 :header-rows: 1
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
300 :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
301
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
302 * - Query parameter
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
303 - Field type
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
304 - Explanation
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
305 * - ``title=foo``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
306 - String
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
307 - 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
308 in the title.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
309 * - ``status=2``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
310 - Link
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
311 - 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
312 * - ``status=open``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
313 - Link
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
314 - 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
315 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
316 * - ``nosy=1``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
317 - MultiLink
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
318 - 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
319 * - ``nosy=admin``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
320 - MultiLink
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
321 - 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
322 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
323 * - ``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
324 values match false.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
325 - Boolean
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
326 - 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
327
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
328 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
329 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
330 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
331 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
332 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
333 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
334
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
335 Searching for strings (e.g. the issue title, or a keyword name)
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
336 performs a case-insensitive substring search, so searching for
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
337 title=Something will find all issues with "Something" or "someThing",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
338 etc. in the title. There is currently no way to perform an exact
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
339 string match.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
340
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
341 To make this clear, searching
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
342 ``https://.../rest/data/issue?keyword=foo`` will not work unless there
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
343 is a keyword with a name field of ``foo`` which is the key field of
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
344 the keyword. However searching the text property ``name`` using
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
345 ``https://.../rest/data/keyword?name=foo`` (note searching keyword
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
346 class not issue class) will return matches for ``foo``, ``foobar``,
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
347 ``foo taz`` etc.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
348
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
349 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
350 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
351
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
352 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
353 need work to allow range searches. Full text search (e.g. over the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
354 body of msgs) is a work in progress.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
355
5865
04deafac71ab Implement sorting of collections in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5863
diff changeset
356 Sorting
04deafac71ab Implement sorting of collections in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5863
diff changeset
357 ^^^^^^^
04deafac71ab Implement sorting of collections in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5863
diff changeset
358
04deafac71ab Implement sorting of collections in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5863
diff changeset
359 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
360 ``@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
361 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
362 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
363 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
364 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
365 and then by id of an issue::
04deafac71ab Implement sorting of collections in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5863
diff changeset
366
04deafac71ab Implement sorting of collections in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5863
diff changeset
367 @sort=status,-id
04deafac71ab Implement sorting of collections in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5863
diff changeset
368
04deafac71ab Implement sorting of collections in REST API
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5863
diff changeset
369
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
370 Pagination
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
371 ^^^^^^^^^^
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
372
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
373 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
374 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
375 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
376
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
377 .. list-table:: Query Parameters Examples
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
378 :header-rows: 1
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
379 :widths: 20 80
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
380
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
381 * - Query parameter
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
382 - Explanation
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
383 * - ``@page_size``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
384 - 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
385 ``@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
386 * - ``@page_index``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
387 - (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
388 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
389
5854
d5aed7106ee6 Need to fix spelling.
John Rouillard <rouilj@ieee.org>
parents: 5843
diff changeset
390 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
391 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
392
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
393 { "data":
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
394 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
395 "collection": { ... },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
396 "@total_size": 222,
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
397 "@links": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
398 "self": [
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
399 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
400 "uri":
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
401 "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
402 "rel": "self"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
403 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
404 ],
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
405 "next": [
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
406 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
407 "uri":
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
408 "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
409 "rel": "next"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
410 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
411 ]
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
412 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
413 }
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
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
416 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
417 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
418 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
419 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
420 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
421 (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
422 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
423
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
424
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
425 Field embedding and verbose output
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
426 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
427
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
428 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
429 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
430 ``@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
431 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
432
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
433 .. list-table:: Query Parameters Examples
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
434 :header-rows: 1
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
435 :widths: 20 80
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
436
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
437 * - Query parameter
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
438 - Explanation
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
439 * - ``@verbose=0``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
440 - 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
441 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
442 * - ``@verbose=1``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
443 - 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
444 is the default.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
445 * - ``@verbose=2``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
446 - 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
447 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
448 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
449 * - ``@verbose=3``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
450 - 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
451 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
452 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
453 * - ``@fields=status,title``
5824
352e78c3b4ab Allow @fields to include protected properties, document @protected
John Rouillard <rouilj@ieee.org>
parents: 5738
diff changeset
454 - 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
455 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
456 @verbose parameter. Protected properties
352e78c3b4ab Allow @fields to include protected properties, document @protected
John Rouillard <rouilj@ieee.org>
parents: 5738
diff changeset
457 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
458
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
459 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
460 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
461 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
462 ``https://.../rest/data/issue?@fields=title`` since the label property
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
463 for an issue is its title. You can use both ``@verbose`` and
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
464 ``@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
465 ``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
466
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
467 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
468 "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
469 "collection": [
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 "link":
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
472 "https://.../rest/data/issue/1",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
473 "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
474 "id": "1",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
475 "status": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
476 "link":
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
477 "https://.../rest/data/status/1",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
478 "id": "1",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
479 "name": "new"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
480 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
481 },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
482 ...
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
483 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
484
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
485 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
486 ``@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
487 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
488
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
489 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
490 "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
491 "collection": [
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
492 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
493 "link":
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
494 "https://.../rest/data/issue/1",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
495 "id": "1",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
496 "status": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
497 "link":
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
498 "https://.../rest/data/status/1",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
499 "id": "1"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
500 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
501 },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
502 ...
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
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
505 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
506 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
507 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
508 output.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
509
5854
d5aed7106ee6 Need to fix spelling.
John Rouillard <rouilj@ieee.org>
parents: 5843
diff changeset
510 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
511 items in the collection.
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 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
514 by these features.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
515
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
516
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
517 Other query params
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
518 ^^^^^^^^^^^^^^^^^^
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
519
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
520 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
521
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
522 .. list-table:: Query Parameters Examples
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
523 :header-rows: 1
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
524 :widths: 20 80
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
525
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
526 * - Query parameter
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
527 - Explanation
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
528 * - ``@pretty=false``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
529 - 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
530 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
531 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
532 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
533 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
534 this time.
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 Using the POST method
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
537 ^^^^^^^^^^^^^^^^^^^^^
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
538
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
539 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
540 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
541 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
542 parameters as the GET method after successful creation.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
543
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
544 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
545 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
546
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
547
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
548 Safely Re-sending POST
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
549 ^^^^^^^^^^^^^^^^^^^^^^
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
550
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
551 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
552 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
553 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
554 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
555
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
556 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
557 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
558 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
559
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
560 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
561 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
562
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
563 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
564
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
565 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
566 -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
567 -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
568 --data '' \
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
569 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
570
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
571 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
572
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
573 {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
574 "data": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
575 "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
576 "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
577 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
578 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
579
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
580 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
581 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
582 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
583
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
584 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
585 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
586 ``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
587
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
588 For example::
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
589
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
590 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
591 -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
592 -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
593 -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
594 --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
595 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
596
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
597 returns::
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
598
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
599 {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
600 "data": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
601 "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
602 "id": "2280"
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
603 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
604 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
605
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
606 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
607 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
608 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
609
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
610 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
611 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
612 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
613 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
614
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
615 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
616 -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
617 --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
618 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
619
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
620 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
621
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
622 {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
623 "data": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
624 "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
625 "link":
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
626 "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
627 }
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
628 }
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
629
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
630 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
631 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
632 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
633
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
634 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
635 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
636 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
637
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
638 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
639
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
640 * 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
641 * 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
642 * 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
643 fails
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
644
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
645 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
646 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
647 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
648 mechanism.
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
649
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
650 .. [#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
651 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
652 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
653 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
654 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
655 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
656 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
657 response was lost.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
658
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
659 Other Supported Methods for Collections
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
660 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
661
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
662 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
663 allowed on a given endpoint.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
664
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
665 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
666
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
667 /data/\ *class*/\ *id* item
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
668 ===========================
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
669
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
670 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
671 (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
672 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
673 (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
674 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
675
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
676 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
677 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
678 account used for the query.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
679
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
680 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
681 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
682 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
683 the fields you are interested in reducing network load as well as
5824
352e78c3b4ab Allow @fields to include protected properties, document @protected
John Rouillard <rouilj@ieee.org>
parents: 5738
diff changeset
684 memory and parsing time on the client side. By default protected
352e78c3b4ab Allow @fields to include protected properties, document @protected
John Rouillard <rouilj@ieee.org>
parents: 5738
diff changeset
685 properties (read only in the database) are not listed. Th
352e78c3b4ab Allow @fields to include protected properties, document @protected
John Rouillard <rouilj@ieee.org>
parents: 5738
diff changeset
686 is makes it easier to submit the attributes from a
352e78c3b4ab Allow @fields to include protected properties, document @protected
John Rouillard <rouilj@ieee.org>
parents: 5738
diff changeset
687 ``@verbose=0`` query using PUT. To include protected properties
5854
d5aed7106ee6 Need to fix spelling.
John Rouillard <rouilj@ieee.org>
parents: 5843
diff changeset
688 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
689 ``@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
690 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
691
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
692 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
693 ``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
694 ``@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
695 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
696 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
697 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
698 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
699 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
700 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
701 @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
702 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
703 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
704 currently discouraged.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
705
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
706 An example of returned values::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
707
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
708 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
709 "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
710 "type": "issue",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
711 "@etag": "\"f15e6942f00a41960de45f9413684591\"",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
712 "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
713 "attributes": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
714 "keyword": [],
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
715 "messages": [
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
716 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
717 "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
718 "id": "375"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
719 },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
720 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
721 "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
722 "id": "376"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
723 },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
724 ...
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
725 ],
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
726 "files": [],
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
727 "status": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
728 "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
729 "id": "2"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
730 },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
731 "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
732 "superseder": [],
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
733 "nosy": [
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
734 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
735 "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
736 "id": "4"
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 "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
740 "id": "5"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
741 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
742 ],
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
743 "assignedto": null,
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 "id": "23"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
746 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
747 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
748
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
749 Retrieve item using key value
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
750 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
751
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
752 If the class has a key attribute, e.g. the 'status' class in the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
753 classic tracker, it can be used to retried the item.
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 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
756 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
757 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
758 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
759 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
760 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
761 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
762 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
763 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
764
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
765 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
766 ``/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
767 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
768
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
769
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
770 Other Supported Methods for Items
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
771 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
772
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
773 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
774 ``/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
775 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
776 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
777 example::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
778
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
779 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
780 --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
781 --header 'X-Requested-With: rest' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
782 --header "Content-Type: application/json" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
783 --header "Accept: application/json" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
784 --header 'If-Match: "dd41f02d6f8b4c34b439fc712b522fb3"' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
785 --data '{ "nosy": [ "1", "5" ] }' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
786 "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
787
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
788 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
789 "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
790 "attribute": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
791 "nosy": [
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
792 "1",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
793 "5"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
794 ]
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
795 },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
796 "type": "issue",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
797 "link":
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
798 "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
799 "id": "23"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
800 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
801 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
802
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
803 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
804
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
805 --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
806
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
807 this is returned::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
808
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
809 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
810 "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
811 "attribute": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
812 "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
813 },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
814 "type": "issue",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
815 "link":
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
816 "https://rouilj.dynamic-dns.net/demo/rest/data/issue/23",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
817 "id": "23"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
818 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
819 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
820
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
821 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
822 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
823 Changing both nosy and title::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
824
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
825 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
826 --header 'Referer: https://.../' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
827 --header 'X-Requested-With: rest' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
828 --header "Content-Type: application/json" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
829 --header "Accept: application/json" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
830 --header 'If-Match: "8209add59a79713d64f4d1a072aef740"' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
831 --data '{ "nosy": [ "4", "5" ], "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
832 "https://rouilj.dynamic-dns.net/demo/rest/data/issue/23"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
833
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
834 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
835
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
836 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
837 "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
838 "attribute": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
839 "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
840 "nosy": [
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
841 "4",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
842 "5"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
843 ]
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
844 },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
845 "type": "issue",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
846 "link":
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
847 "https://rouilj.dynamic-dns.net/demo/rest/data/issue/23",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
848 "id": "23"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
849 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
850 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
851
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
852 Note that 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
853 work. So using::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
854
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
855 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
856
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
857 doesn't have the desired effect. However it can be put in the data
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
858 payload:
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
859
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
860 curl -u admin:admin ...
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
861 --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
862
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
863 produces::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
864
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
865 {"data": {"attribute": {}, "type": "issue",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
866 "link": "https://...", "id": "23"}}
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
867
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
868 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
869 line.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
870
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
871 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
872 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
873 will only return a status code. The item is still available if
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
874 accessed directly by it's item url. The item will not show up in
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
875 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
876
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
877 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
878 ``/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
879 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
880 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
881 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
882 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
883 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
884 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
885 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
886 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
887 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
888 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
889 method. An example to add a user to the nosy list of an item is:
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
890
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
891 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
892 --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
893 --header "Accept: application/json" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
894 --header 'If-Match: "c6e2d81019acff1da7a2da45f93939bd"' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
895 --data-urlencode '@op=add' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
896 --data 'nosy=3' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
897 "https://.../rest/data/issue/23"
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 which returns::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
900
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
901 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
902 "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
903 "attribute": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
904 "nosy": [
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
905 "3",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
906 "4"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
907 ]
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
908 },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
909 "type": "issue",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
910 "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
911 "id": "23"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
912 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
913 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
914
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
915 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
916 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
917
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
918 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
919 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
920 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
921 ``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
922 ``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
923 ``@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
924 ``If-Match`` header.
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 /data/\ *class*/\ *id*/\ *property* field
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 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
930 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
931 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
932
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
933 For example::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
934
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
935 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
936 "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
937 "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
938 "data": "I need Broken PC",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
939 "type": "<class 'str'>",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
940 "id": "22",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
941 "@etag": "\"370510512b2d8fc3f98aac3d762cc7b1\""
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
942 }
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 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
947 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
948
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
949 Other Supported Methods for fields
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
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
952 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
953 ``/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
954 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
955 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
956 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
957
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
958 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
959 --header "Accept: application/json" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
960 --data "data=Provisional" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
961 --header "If-Match: 079eba599152f3eed00567e23258fecf" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
962 --data-urlencode "@etag=079eba599152f3eed00567e23258fecf" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
963 "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
964
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
965 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
966 type::
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 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
969 --header "Accept: application/json" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
970 --header 'Content-Type: application/json' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
971 --header "Referer: https://.../" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
972 --header "x-requested-with: rest" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
973 --header 'If-Match: "e2e6cc43c3475a4a3d9e5343617c11c3"' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
974 --data '{"leadtime": "2d" }' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
975 "https://.../rest/data/issue/10"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
976
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
977 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
978 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
979 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
980 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
981
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
982 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
983 ``/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
984 ``@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
985 ``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
986 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
987 ``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
988 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
989 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
990 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
991 method.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
992
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
993 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
994 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
995 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
996 ``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
997 ``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
998 ``@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
999 ``If-Match`` header.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1000
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1001 Tunneling Methods via POST
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1002 ==========================
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1003
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1004 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
1005 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
1006 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
1007 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
1008 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
1009 without tunneling.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1010
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1011 Examples and Use Cases
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1012 ----------------------
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1013
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1014 sample python client
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1015 ====================
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1016
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1017 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
1018 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
1019
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1020
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1021 >>> import requests
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1022 >>> 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
1023 >>> s = requests.session()
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1024 >>> 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
1025 >>> if r.status_code != 200:
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1026 ... 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
1027 ... exit(1)
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1028 >>> print (r.json() ['data']['data']
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1029 TEST Title
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1030 >>> 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
1031 >>> 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
1032 >>> 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
1033 ... 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
1034 ... exit(1)
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1035 >>> print(r.json())
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1036
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1037 Retire/Restore::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1038 >>> 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
1039 >>> print (r.json())
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1040 >>> 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
1041 >>> etag = r.headers['ETag']
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1042 >>> print("ETag: %s" % etag)
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1043 >>> etag = r.json()['data']['@etag']
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1044 >>> print("@etag: %s" % etag)
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1045 >>> h = {'If-Match': etag,
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1046 ... 'X-Requested-With': 'rest',
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1047 ... '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
1048 >>> 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
1049 >>> 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
1050 >>> print(r.json())
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1051 >>> 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
1052 >>> 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
1053 >>> print(r.json())
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1054
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1055 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
1056 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
1057 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
1058 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
1059
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
1060
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
1061 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
1062 ======================
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1063
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1064 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
1065 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
1066 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
1067 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
1068
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1069 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
1070 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
1071 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
1072
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1073 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
1074 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
1075
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
1076 $('#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
1077 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
1078 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
1079 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
1080 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
1081 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
1082 $.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
1083 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
1084 + 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
1085 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
1086 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
1087 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
1088 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
1089
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1090 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
1091 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
1092 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
1093
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
1094 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
1095
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1096 {
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1097 "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
1098 "@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
1099 "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
1100 {
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1101 "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
1102 "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
1103 "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
1104 },
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1105 {
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1106 "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
1107 "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
1108 "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
1109 },
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
1110 ...
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
1111
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1112 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
1113 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
1114 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
1115 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
1116 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
1117 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
1118 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
1119
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
1120 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
1121
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1122 .../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
1123
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1124 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
1125 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
1126
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1127 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
1128 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
1129 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
1130 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
1131 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
1132
5723
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 "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
1135 "title": "Request for Broken PC",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1136 "id": "1001",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1137 "status": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1138 "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
1139 "id": "6",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1140 "name": "resolved"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1141 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1142 }
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
1143
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
1144 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
1145
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1146 === 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
1147 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
1148 === 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
1149 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
1150 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
1151
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1152 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
1153 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
1154
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1155
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1156 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
1157 ------------------------
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1158
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1159 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
1160 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
1161 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
1162
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1163 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
1164 =========================
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1165
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1166 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
1167 directory.
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1168
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1169 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
1170
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1171 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
1172 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
1173
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1174 class RestfulInstance:
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1175
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1176 @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
1177 @_data_decorator
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1178 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
1179 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
1180 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
1181
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1182 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
1183
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1184 $ 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
1185 {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1186 "data": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1187 "hello": "world"
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1188 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1189 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1190
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1191 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
1192
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1193 # 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
1194 @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
1195 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
1196 result = { "schema": {} }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1197 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
1198 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
1199 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
1200
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1201 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
1202 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
1203 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
1204
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1205 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
1206 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
1207
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1208 return result
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1209
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1210 ..
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1211 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
1212
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1213 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
1214
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1215 $ 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
1216 {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1217 "schema": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1218 "keyword": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1219 "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
1220 },
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1221 "title": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1222 "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
1223 },
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1224 "files": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1225 "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
1226 },
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1227 "status": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1228 "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
1229 }, ...
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1230 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1231 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1232
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1233
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1234 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
1235 ``/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
1236
5883
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1237 Redefine/move rest endpoints
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1238 ============================
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1239
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1240 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
1241 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
1242
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1243 @Routing.route("/summary")
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1244 @_data_decorator
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1245 def summary2(self, input):
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1246 result = { "hello": "world" }
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1247 return 200, result
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1248
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1249 will return::
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1250
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1251 {
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1252 "data": {
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1253 "hello": "world"
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1254 }
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1255 }
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1256
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1257
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1258 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
1259 endpoints to new locations. Adding::
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1260
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1261 @Routing.route("/data2/<:classname>")
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1262 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
1263 """ 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
1264
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1265 Existing function is decorated with:
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1266
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1267 @Routing.route("/data/<:classname>")
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1268 @_data_decorator
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1269
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1270 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
1271 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
1272 """
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1273 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
1274
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1275 will move the response that normally happens at /rest/data/<class> to
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1276 /rest/data/<class>.
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1277
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1278
5843
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1279 Controlling Access to Backend Data
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1280 ==================================
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1281
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1282 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
1283 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
1284 seen.
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1285
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1286 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
1287 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
1288 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
1289 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
1290 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
1291 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
1292 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
1293 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
1294 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
1295 permission.
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1296
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1297 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
1298 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
1299 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
1300 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
1301 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
1302
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1303 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
1304 from cgi import MiniFieldStorage
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1305
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1306 class RestfulInstance(object):
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1307
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1308 @Routing.route("/data/@permission/Developer")
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1309 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
1310 '''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
1311 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
1312
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1313 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
1314 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
1315 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
1316 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
1317 @verbose) are supported.
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1318
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1319 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
1320 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
1321 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
1322 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
1323 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
1324 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
1325 '''
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1326 # get real user id
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1327 realuid=self.db.getuid()
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1328
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1329 def allowed_field(fs):
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1330 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
1331 # 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
1332 return True
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1333 elif fs.name in [ '@fields' ]:
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1334 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
1335 # 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
1336 # @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
1337 # 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
1338 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
1339 'View', realuid, 'user', property=prop,
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1340 itemid='1'):
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1341 return False
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1342 return True
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1343 elif fs.name.startswith("@"):
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1344 # allow @page..., @verbose etc.
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1345 return True
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1346
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1347 # deny all other url parmeters
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1348 return False
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1349
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1350 # 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
1351 # 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
1352 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
1353 if allowed_field(fs) ]
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1354
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1355 # 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
1356 # search
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1357 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
1358
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1359 # 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
1360 self.db.setCurrentUser('admin')
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1361
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1362 # 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
1363 # 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
1364 # 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
1365 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
1366
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1367 Calling this with: `curl 'http://example.com/demo/rest/data/@permission/Developer?@fields=realname&roles=Users&@verbose=2'`
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1368 produces output similar to::
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1369
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1370 {
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1371 "data": {
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1372 "collection": [
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1373 {
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1374 "username": "agent",
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1375 "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
1376 "realname": "James Bond",
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1377 "id": "4"
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1378 }
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1379 ],
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1380 "@total_size": 1
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1381 }
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1382 }
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1383
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1384 assuming user 4 is the only user with the Developer role. Note that
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1385 the url passes the `roles=User` filter option which is silently
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1386 ignored.
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1387
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1388 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
1389 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1390
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1391 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
1392 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
1393 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
1394 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
1395 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
1396 issue.
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1397
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1398 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
1399 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
1400 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
1401
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1402 So what we need is a way for this third part service to impersonate
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1403 you and have access to create a roundup timelog entry (see
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1404 `<customizing.html#adding-a-time-log-to-your-issues>`__. Then add it
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1405 to the associated issue. This should happen without sharing passwords
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1406 and without the third party service to see the issue (except the
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1407 ``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
1408
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1409 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
1410 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
1411
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1412 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
1413
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1414 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
1415 jwt module you will see the error ``Support for jwt disabled.``
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1416 2. create a new role that allows Create access to timelog and edit
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1417 access to an issues' ``times`` property.
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1418 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
1419 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
1420 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
1421 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
1422 ``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
1423 5. add an auditor to make sure that users with this role are appending
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1424 timelog links to the `times` property of the issue.
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1425
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1426 Create role
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1427 """""""""""
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1428
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1429 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
1430 proper authorization::
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1431
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1432 db.security.addRole(name="User:timelog", description="allow a user to create and append timelogs")
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1433 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
1434 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
1435 db.security.addPermissionToRole("User:timelog", perm)
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1436 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
1437 properties=('id', 'times'),
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1438 description="Allow editing timelog for issue", props_only=False)
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1439 db.security.addPermissionToRole("User:timelog", perm)
5879
94a7669677ae add permissions to control user of rest and xmlrpc API interfaces.
John Rouillard <rouilj@ieee.org>
parents: 5878
diff changeset
1440 db.security.addPermissionToRole('User:timelog', 'Rest Access')
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1441
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1442 Then role is named to work with the jwt issue rest call. Starting the role
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1443 name with ``User:`` allows the jwt issue code to create a token with
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1444 this role if the user requesting the role has the User role.
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1445
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1446 Create rest endpoints
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1447 """""""""""""""""""""
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1448
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1449 Here is code to add to your tracker's ``interfaces.py`` (note code is
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1450 python3)::
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1451
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1452 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
1453
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1454 class RestfulInstance(object):
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1455 @Routing.route("/jwt/issue", 'POST')
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1456 @_data_decorator
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1457 def generate_jwt(self, input):
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1458 import jwt
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1459 import datetime
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1460 from roundup.anypy.strings import b2s
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1461
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1462 # require basic auth to generate a token
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1463 # At some point we can support a refresh token.
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1464 # maybe a jwt with the "refresh": True claim generated
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1465 # using: "refresh": True in the json request payload.
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1466
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1467 denialmsg='Token creation requires login with basic auth.'
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1468 if 'HTTP_AUTHORIZATION' in self.client.env:
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1469 try:
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1470 auth = self.client.env['HTTP_AUTHORIZATION']
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1471 scheme, challenge = auth.split(' ', 1)
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1472 except (ValueError, AttributeError):
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1473 # bad format for header
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1474 raise Unauthorised(denialmsg)
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1475 if scheme.lower() != 'basic':
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1476 raise Unauthorised(denialmsg)
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1477 else:
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1478 raise Unauthorised(denialmsg)
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1479
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1480 # If we reach this point we have validated that the user has
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1481 # logged in with a password using basic auth.
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1482 all_roles = list(self.db.security.role.items())
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1483 rolenames = []
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1484 for role in all_roles:
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1485 rolenames.append(role[0])
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1486
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1487 user_roles = list(self.db.user.get_roles(self.db.getuid()))
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1488
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1489 claim= { 'sub': self.db.getuid(),
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1490 'iss': self.db.config.TRACKER_WEB,
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1491 'aud': self.db.config.TRACKER_WEB,
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1492 'iat': datetime.datetime.utcnow(),
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1493 }
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1494
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1495 lifetime = 0
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1496 if 'lifetime' in input:
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1497 if input['lifetime'].value != 'unlimited':
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1498 try:
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1499 lifetime = datetime.timedelta(seconds=int(input['lifetime'].value))
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1500 except ValueError:
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1501 raise UsageError("Value 'lifetime' must be 'unlimited' or an integer to specify" +
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1502 " lifetime in seconds. Got %s."%input['lifetime'].value)
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1503 else:
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1504 lifetime = datetime.timedelta(seconds=86400) # 1 day by default
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1505
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1506 if lifetime: # if lifetime = 0 make unlimited by omitting exp claim
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1507 claim['exp'] = datetime.datetime.utcnow() + lifetime
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1508
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1509 newroles = []
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1510 if 'roles' in input:
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1511 for role in input['roles'].value:
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1512 if role not in rolenames:
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1513 raise UsageError("Role %s is not valid."%role)
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1514 if role in user_roles:
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1515 newroles.append(role)
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1516 continue
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1517 parentrole = role.split(':', 1)[0]
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1518 if parentrole in user_roles:
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1519 newroles.append(role)
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1520 continue
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1521
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1522 raise UsageError("Role %s is not permitted."%role)
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1523
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1524 claim['roles'] = newroles
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1525 else:
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1526 claim['roles'] = user_roles
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1527 secret = self.db.config.WEB_JWT_SECRET
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1528 myjwt = jwt.encode(claim, secret, algorithm='HS256')
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1529
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1530 result = {"jwt": b2s(myjwt),
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1531 }
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1532
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1533 return 200, result
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1534
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1535 @Routing.route("/jwt/validate", 'GET')
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1536 @_data_decorator
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1537 def validate_jwt(self,input):
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1538 import jwt
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1539 if not 'jwt' in input:
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1540 raise UsageError("jwt key must be specified")
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1541
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1542 myjwt = input['jwt'].value
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1543
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1544 secret = self.db.config.WEB_JWT_SECRET
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1545 try:
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1546 result = jwt.decode(myjwt, secret,
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1547 algorithms=['HS256'],
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1548 audience=self.db.config.TRACKER_WEB,
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1549 issuer=self.db.config.TRACKER_WEB,
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1550 )
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1551 except jwt.exceptions.InvalidTokenError as err:
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1552 return 401, str(err)
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1553
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1554 return 200, result
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1555
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1556 **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
1557 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
1558 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
1559 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
1560 username/password authentication.
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1561
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1562 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
1563 providing patches to existing code to:
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1564
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1565 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
1566 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
1567 roundup core
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1568 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
1569 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
1570
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1571 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
1572
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1573 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
1574 -H "X-requested-with: rest" \
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1575 -H "Content-Type: application/json" \
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1576 --data '{"lifetime": "3600", "roles": [ "user:timelog" ] }' \
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1577 https://.../demo/rest/jwt/issue
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1578
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1579 (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
1580
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1581 {
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1582 "data": {
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1583 "jwt": "eyJ0eXAiOiJK......XxMDb-Q3oCnMpyhxPXMAk"
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1584 }
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1585 }
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1586
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1587 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
1588 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
1589
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1590
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1591 curl -s -H "Referer: https://.../demo/" \
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1592 -H "X-requested-with: rest" \
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1593 https://rouilj.dynamic-dns.net/demo/rest/jwt/validate?jwt=eyJ0eXAiOiJK......XxMDb-Q3oCnMpyhxPXMAk
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1594
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1595 (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
1596
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1597 {
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1598 "data": {
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1599 "user": "3",
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1600 "roles": [
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1601 "user:timelog"
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1602 ],
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1603 "iss": "https://.../demo/",
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1604 "aud": "https://.../demo/",
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1605 "iat": 1569542404,
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1606 "exp": 1569546004
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1607 }
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1608 }
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1609
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1610 Final steps
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1611 ^^^^^^^^^^^
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1612
5883
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1613 See the `upgrading directions`_ on how to use the ``updateconfig`` to
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1614 generate an updated copy of config.ini using roundup-admin. Then set
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1615 the ``jwt_secret`` to at least 32 characters (more is better up to 512
da417bab5cb8 Add more programming rest interface examples. Fix broken link.
John Rouillard <rouilj@ieee.org>
parents: 5879
diff changeset
1616 bits).
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1617
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1618 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
1619 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
1620 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
1621 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
1622 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
1623 https://issues.roundup-tracker.org/.)
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1624
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1625 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
1626 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
1627 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
1628 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
1629 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
1630 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
1631
5843
da1f40b5148d issue2551050 document mechanism to allow uers limited access to
John Rouillard <rouilj@ieee.org>
parents: 5826
diff changeset
1632
5737
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
1633 Creating Custom Rate Limits
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
1634 ===========================
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
1635
5738
9777d7311bc0 Clean up the custom rate limit doc.
John Rouillard <rouilj@ieee.org>
parents: 5737
diff changeset
1636 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
1637 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
1638 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
1639
9777d7311bc0 Clean up the custom rate limit doc.
John Rouillard <rouilj@ieee.org>
parents: 5737
diff changeset
1640 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
1641 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
1642 ``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
1643 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
1644
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
1645 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
1646 from datetime import timedelta
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
1647
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
1648 def grl(self):
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
1649 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
1650 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
1651
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
1652 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
1653
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
1654 uid = self.db.getuid()
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
1655 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
1656 node = class_obj.getnode(uid)
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
1657
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
1658 # 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
1659 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
1660 # 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
1661 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
1662
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
1663 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
1664 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
1665 else:
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
1666 # 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
1667 return None
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
1668
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
1669 RestfulInstance.getRateLimit = grl
07d8bbf6ee5f Add example on overriding RestfulInstance.getRateLimit from interfaces.py.
John Rouillard <rouilj@ieee.org>
parents: 5723
diff changeset
1670
5738
9777d7311bc0 Clean up the custom rate limit doc.
John Rouillard <rouilj@ieee.org>
parents: 5737
diff changeset
1671 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
1672 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
1673 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
1674 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
1675
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1676 Test Examples
5878
1b57d8f3eb97 Add rudimentery experiment JSON Web Token (jwt) support
John Rouillard <rouilj@ieee.org>
parents: 5865
diff changeset
1677 ^^^^^^^^^^^^^
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1678
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1679 Rate limit tests:
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1680
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1681 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
1682 https://.../rest/data/status/new \# | grep Remaining
Roundup Issue Tracker: http://roundup-tracker.org/