Mercurial > p > roundup > code
comparison doc/rest.txt @ 6674:ff8845ca305e
issue2551203 - CORS and CORS preflight documentation.
Add documentation on CORS preflight and CORS requests in REST.
| author | John Rouillard <rouilj@ieee.org> |
|---|---|
| date | Thu, 12 May 2022 17:15:15 -0400 |
| parents | 0351caa802f7 |
| children | 7542269becfa |
comparison
equal
deleted
inserted
replaced
| 6673:567283742a5c | 6674:ff8845ca305e |
|---|---|
| 200 not be sent. | 200 not be sent. |
| 201 | 201 |
| 202 Otherwise Content-Type is allowed to be ``application/json`` or | 202 Otherwise Content-Type is allowed to be ``application/json`` or |
| 203 ``application/x-www-form-urlencoded``. Any other value returns error | 203 ``application/x-www-form-urlencoded``. Any other value returns error |
| 204 code 415. | 204 code 415. |
| 205 | |
| 206 CORS preflight requests | |
| 207 ^^^^^^^^^^^^^^^^^^^^^^^ | |
| 208 | |
| 209 CORS preflight requests are done using the OPTIONS method. They | |
| 210 require that REST be enabled. These requests do not make any changes | |
| 211 or get any information from the database. As a result they are | |
| 212 available to the anonymous user and any authenticated user. The user | |
| 213 does not need to have `Rest Access` permissions. Also these requests | |
| 214 bypass CSRF checks. | |
| 215 | |
| 216 The headers: | |
| 217 | |
| 218 * `Access-Control-Request-Headers` | |
| 219 * `Access-Control-Request-Method` | |
| 220 * `Origin` | |
| 221 | |
| 222 must all be present. The 204 response will include: | |
| 223 | |
| 224 * `Access-Control-Allow-Origin` | |
| 225 * `Access-Control-Allow-Headers` | |
| 226 * `Access-Control-Allow-Methods` | |
| 227 * `Access-Control-Allow-Credentials: true` | |
| 228 * `Access-Control-Max-Age: 86400` | |
| 229 | |
| 230 If the endpoint accepts the PATCH verb the header `Accept-Patch` with | |
| 231 valid mime types (usually `application/x-www-form-urlencoded, | |
| 232 multipart/form-data`) will be included. | |
| 233 | |
| 234 It will also include rate limit headers since the request is included | |
| 235 in the rate limit for the URL. The results from the CORS preflight | |
| 236 should be cached for a week so preflight requests are not expected to | |
| 237 cause a problem. If it is an issue, you can see | |
| 238 `Creating Custom Rate Limits`_ | |
| 239 and craft a rate limiter that ignores anonymous OPTIONS requests. | |
| 240 | |
| 241 Support for filtering by ORIGIN is not included. If you want to add | |
| 242 this, see `Programming the REST API`_ on directions for overriding | |
| 243 existing endpoints with a wrapper that can verify the ORIGIN. | |
| 205 | 244 |
| 206 Response Formats | 245 Response Formats |
| 207 ================ | 246 ================ |
| 208 | 247 |
| 209 The default response format is json. | 248 The default response format is json. |
| 1405 >>> print(r.json()) | 1444 >>> print(r.json()) |
| 1406 | 1445 |
| 1407 Note the addition of headers for: x-requested-with and referer. This | 1446 Note the addition of headers for: x-requested-with and referer. This |
| 1408 allows the request to pass the CSRF protection mechanism. You may need | 1447 allows the request to pass the CSRF protection mechanism. You may need |
| 1409 to add an Origin header if this check is enabled in your tracker's | 1448 to add an Origin header if this check is enabled in your tracker's |
| 1410 config.ini (look for csrf_enforce_header_origin). | 1449 config.ini (look for csrf_enforce_header_origin). (Note the Origin |
| 1450 header check may have to be disabled if an application is making a | |
| 1451 CORS request to the Roundup server.) | |
| 1411 | 1452 |
| 1412 A similar curl based retire example is to use:: | 1453 A similar curl based retire example is to use:: |
| 1413 | 1454 |
| 1414 curl -s -u admin:admin \ | 1455 curl -s -u admin:admin \ |
| 1415 -H "Referer: https://tracker.example.com/demo/" \ | 1456 -H "Referer: https://tracker.example.com/demo/" \ |
| 2054 Creating Custom Rate Limits | 2095 Creating Custom Rate Limits |
| 2055 =========================== | 2096 =========================== |
| 2056 | 2097 |
| 2057 You can replace the default rate limiter that is configured using | 2098 You can replace the default rate limiter that is configured using |
| 2058 the tracker's ``config.ini``. You can return different rate | 2099 the tracker's ``config.ini``. You can return different rate |
| 2059 limits based on the user, time of day, phase of moon etc. | 2100 limits based on the user, time of day, phase of moon, request |
| 2101 method (via self.client.request.command) etc. | |
| 2060 | 2102 |
| 2061 Assume you add two integer valued properties to the user | 2103 Assume you add two integer valued properties to the user |
| 2062 object. Let's call them ``rate_limit_interval`` and | 2104 object. Let's call them ``rate_limit_interval`` and |
| 2063 ``rate_limit_calls``. Add code similar to this to interfaces.py | 2105 ``rate_limit_calls``. Add code similar to this to interfaces.py |
| 2064 to override the default rate limiter code:: | 2106 to override the default rate limiter code:: |