Mercurial > p > roundup > code

comparison doc/rest.txt @ 7464:82bbb95e5690 issue2550923_computed_property

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
merge from tip into issue2550923_computed_property
author John Rouillard <rouilj@ieee.org>
date Thu, 08 Jun 2023 00:10:32 -0400
parents f53de10ea8ea
children f8b5b0310f88
comparison
equal deleted inserted replaced
7045:ca90f7270cd4 7464:82bbb95e5690
1 .. meta:: 1 .. meta::
2 :description: 2 :description:
3 Documentation on the RESTful interface to the Roundup Issue 3 Documentation on the RESTful interface to the Roundup Issue
4 Tracker. 4 Tracker. Enable REST access, endpoints, methods,
5 5 authentication, discovery.
6 6
7 .. index:: pair: api; Representational state transfer 7 .. index:: pair: api; Representational state transfer
8 pair: api; rest 8 pair: api; rest
9 9
10 ==================== 10 ====================
147 147
148 **Sunset**: an http date after which the end point will not be 148 **Sunset**: an http date after which the end point will not be
149 available. This is not returned by current code, but can be used 149 available. This is not returned by current code, but can be used
150 when `Programming the REST API`_. It should be used as a hint that 150 when `Programming the REST API`_. It should be used as a hint that
151 the REST endpoint will be going away. See 151 the REST endpoint will be going away. See
152 https://tools.ietf.org/html/rfc8594 for details on this header and 152 https://www.rfc-editor.org/rfc/rfc8594 for details on this header and
153 the sunset link type. 153 the sunset link type.
154 154
155 Hyperdb Stats 155 Hyperdb Stats
156 ============= 156 =============
157 157
229 229
230 * `Access-Control-Request-Headers` 230 * `Access-Control-Request-Headers`
231 * `Access-Control-Request-Method` 231 * `Access-Control-Request-Method`
232 * `Origin` 232 * `Origin`
233 233
234 The 204 response will include the headers: 234 The headers of the 204 response depend on the
235 ``allowed_api_origins`` setting. If a ``*`` is included as the
236 first element, any client can read the data but they can not
237 provide authentication. This limits the available data to what
238 the anonymous user can see in the web interface.
239
240 All 204 responses will include the headers:
235 241
236 * `Access-Control-Allow-Origin` 242 * `Access-Control-Allow-Origin`
237 * `Access-Control-Allow-Headers` 243 * `Access-Control-Allow-Headers`
238 * `Access-Control-Allow-Methods` 244 * `Access-Control-Allow-Methods`
245 * `Access-Control-Max-Age: 86400`
246
247 If the client's ORIGIN header matches an entry besides ``*`` in the
248 ``allowed_api_origins`` it will also include:
249
239 * `Access-Control-Allow-Credentials: true` 250 * `Access-Control-Allow-Credentials: true`
240 * `Access-Control-Max-Age: 86400` 251
241 252 permitting the client to log in and perform authenticated operations.
253
242 If the endpoint accepts the PATCH verb the header `Accept-Patch` with 254 If the endpoint accepts the PATCH verb the header `Accept-Patch` with
243 valid mime types (usually `application/x-www-form-urlencoded, 255 valid mime types (usually `application/x-www-form-urlencoded,
244 multipart/form-data`) will be included. 256 multipart/form-data`) will be included.
245 257
246 It will also include rate limit headers since the request is included 258 It will also include rate limit headers since the request is included
876 a PUT or DELETE, retrying the interrupted POST may result in the 888 a PUT or DELETE, retrying the interrupted POST may result in the
877 creation of a duplicate issue. 889 creation of a duplicate issue.
878 890
879 To solve this problem, a two step process inspired by the POE - Post 891 To solve this problem, a two step process inspired by the POE - Post
880 Once Exactly spec: 892 Once Exactly spec:
881 https://tools.ietf.org/html/draft-nottingham-http-poe-00 is provided. 893 https://datatracker.ietf.org/doc/html/draft-nottingham-http-poe-00 is provided.
882 894
883 This mechanism returns a single use URL. POSTing to the URL creates 895 This mechanism returns a single use URL. POSTing to the URL creates
884 a new object in the class. 896 a new object in the class.
885 897
886 First we get the URL. Here is an example using curl:: 898 First we get the URL. Here is an example using curl::
1409 ``If-Match`` header. 1421 ``If-Match`` header.
1410 1422
1411 Tunneling Methods via POST 1423 Tunneling Methods via POST
1412 ========================== 1424 ==========================
1413 1425
1414 If you are working through a proxy and unable to use http method like 1426 If you are working through a proxy and unable to use http methods like
1415 PUT, PATCH or DELETE you can use POST to perform the action. To tunnel 1427 PUT, PATCH, or DELETE, you can use POST to perform the action. To tunnel
1416 an action through POST, send the ``X-HTTP-METHOD-OVERRIDE`` header 1428 an action through POST, send the ``X-HTTP-METHOD-OVERRIDE`` header
1417 with a value of DELETE or other capitalized HTTP verb. The body of the 1429 with a value of DELETE or other capitalized HTTP verb. The body of the
1418 POST should be what you would send if you were using the method 1430 POST should be what you would send if you were using the method
1419 without tunneling. 1431 without tunneling.
1420 1432
1847 username and credentials. Especially if your roundup instance is under 1859 username and credentials. Especially if your roundup instance is under
1848 your company's single sign on infrastructure. 1860 your company's single sign on infrastructure.
1849 1861
1850 So what we need is a way for this third party service to impersonate 1862 So what we need is a way for this third party service to impersonate
1851 you and have access to create a roundup timelog entry (see 1863 you and have access to create a roundup timelog entry (see
1852 `<customizing.html#adding-a-time-log-to-your-issues>`__ ). Then add it 1864 `<customizing.html#adding-a-time-log-to-your-issues>`_). Then add it
1853 to the associated issue. This should happen without sharing passwords 1865 to the associated issue. This should happen without sharing passwords
1854 and without allowing the third party service to see the issue (except the 1866 and without allowing the third party service to see the issue (except the
1855 ``times`` property), user, or other information in the tracker. 1867 ``times`` property), user, or other information in the tracker.
1856 1868
1857 Enter the use of a JSON web token. Roundup has rudimentary ability to 1869 Enter the use of a JSON web token. Roundup has rudimentary ability to
2043 username/password authentication. 2055 username/password authentication.
2044 2056
2045 Currently use of JWTs an experiment. If this appeals to you consider 2057 Currently use of JWTs an experiment. If this appeals to you consider
2046 providing patches to existing code to: 2058 providing patches to existing code to:
2047 2059
2048 1. record all JWTs created by a user 2060 1. create long lived refresh tokens
2049 2. using the record to allow JWTs to be revoked and ignored by the 2061 2. record all refresh tokens created by a user
2050 roundup core 2062 3. using the record to allow refresh tokens to be revoked and
2051 3. provide a UI page for managing/revoking JWTs 2063 ignored by the roundup core
2052 4. provide a rest api for revoking JWTs 2064 4. provide a UI page for managing/revoking refresh tokens
2065 5. provide a rest api for revoking refresh tokens
2053 2066
2054 These end points can be used like:: 2067 These end points can be used like::
2055 2068
2056 curl -u demo -s -X POST -H "Referer: https://.../demo/" \ 2069 curl -u demo -s -X POST -H "Referer: https://.../demo/" \
2057 -H "X-requested-with: rest" \ 2070 -H "X-requested-with: rest" \
Roundup Issue Tracker: http://roundup-tracker.org/