Mercurial > p > roundup > code
comparison doc/rest.txt @ 5895:93bbe5340d5b
More typo fixes and verbatim blocks.
| author | John Rouillard <rouilj@ieee.org> |
|---|---|
| date | Wed, 02 Oct 2019 21:51:27 -0400 |
| parents | 45a104bb127e |
| children | a8df94ec8040 |
comparison
equal
deleted
inserted
replaced
| 5894:45a104bb127e | 5895:93bbe5340d5b |
|---|---|
| 748 | 748 |
| 749 Retrieve item using key value | 749 Retrieve item using key value |
| 750 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | 750 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 751 | 751 |
| 752 If the class has a key attribute, e.g. the 'status' class in the | 752 If the class has a key attribute, e.g. the 'status' class in the |
| 753 classic tracker, it can be used to retried the item. | 753 classic tracker, it can be used to retrieve the item. |
| 754 | 754 |
| 755 You can get an individual status by specifying the key-attribute value | 755 You can get an individual status by specifying the key-attribute value |
| 756 e.g. ``/data/status/name=closed``. Note that ``name`` in this example | 756 e.g. ``/data/status/name=closed``. Note that ``name`` in this example |
| 757 must be the key-attribute of the class. A short-form (which might not | 757 must be the key-attribute of the class. A short-form (which might not |
| 758 be supported in future version of the API) is to specify only the | 758 be supported in future version of the API) is to specify only the |
| 853 work. So using:: | 853 work. So using:: |
| 854 | 854 |
| 855 https://.../rest/data/issue/23?@pretty=false | 855 https://.../rest/data/issue/23?@pretty=false |
| 856 | 856 |
| 857 doesn't have the desired effect. However it can be put in the data | 857 doesn't have the desired effect. However it can be put in the data |
| 858 payload: | 858 payload:: |
| 859 | 859 |
| 860 curl -u admin:admin ... | 860 curl -u admin:admin ... |
| 861 --data '{ "nosy": [ "4", "5" ], "title": "...", "@pretty": "false" }' | 861 --data '{ "nosy": [ "4", "5" ], "title": "...", "@pretty": "false" }' |
| 862 | 862 |
| 863 produces:: | 863 produces:: |
| 869 line. | 869 line. |
| 870 | 870 |
| 871 The method ``DELETE`` is allowed on items, e.g., ``/data/issue/42`` | 871 The method ``DELETE`` is allowed on items, e.g., ``/data/issue/42`` |
| 872 and will retire (mark as deleted) the respective item. On success it | 872 and will retire (mark as deleted) the respective item. On success it |
| 873 will only return a status code. The item is still available if | 873 will only return a status code. The item is still available if |
| 874 accessed directly by it's item url. The item will not show up in | 874 accessed directly by its item url. The item will not show up in |
| 875 searches where it would have been matched if not retired. | 875 searches where it would have been matched if not retired. |
| 876 | 876 |
| 877 Finally the ``PATCH`` method can be applied to individual items, e.g., | 877 Finally the ``PATCH`` method can be applied to individual items, e.g., |
| 878 ``/data/issue/42``. This method gets an operator ``@op=<method>`` | 878 ``/data/issue/42``. This method gets an operator ``@op=<method>`` |
| 879 where ``<method>`` is one of ``add``, ``replace``, ``remove``. For | 879 where ``<method>`` is one of ``add``, ``replace``, ``remove``. For |
| 884 supplied. Currently there are only two actions, neither has args, | 884 supplied. Currently there are only two actions, neither has args, |
| 885 namely ``retire`` and ``restore``. The ``retire`` action on an item is | 885 namely ``retire`` and ``restore``. The ``retire`` action on an item is |
| 886 the same as a ``DELETE`` method, it retires the item. The ``restore`` | 886 the same as a ``DELETE`` method, it retires the item. The ``restore`` |
| 887 action is the inverse of ``retire``, the item is again visible. On | 887 action is the inverse of ``retire``, the item is again visible. On |
| 888 success the returned value is the same as the respective ``GET`` | 888 success the returned value is the same as the respective ``GET`` |
| 889 method. An example to add a user to the nosy list of an item is: | 889 method. An example to add a user to the nosy list of an item is:: |
| 890 | 890 |
| 891 curl -u admin:admin -p -X PATCH \ | 891 curl -u admin:admin -p -X PATCH \ |
| 892 --header "Content-Type: application/x-www-form-urlencoded" \ | 892 --header "Content-Type: application/x-www-form-urlencoded" \ |
| 893 --header "Accept: application/json" \ | 893 --header "Accept: application/json" \ |
| 894 --header 'If-Match: "c6e2d81019acff1da7a2da45f93939bd"' \ | 894 --header 'If-Match: "c6e2d81019acff1da7a2da45f93939bd"' \ |
| 1362 # Once we have cleaned up the request, pass it to | 1362 # Once we have cleaned up the request, pass it to |
| 1363 # get_collection as though /rest/data/users?... has been called | 1363 # get_collection as though /rest/data/users?... has been called |
| 1364 # to get @verbose and other args supported. | 1364 # to get @verbose and other args supported. |
| 1365 return self.get_collection('user', input) | 1365 return self.get_collection('user', input) |
| 1366 | 1366 |
| 1367 Calling this with: `curl 'http://example.com/demo/rest/data/@permission/Developer?@fields=realname&roles=Users&@verbose=2'` | 1367 Calling this with:: |
| 1368 | |
| 1369 curl 'http://example.com/demo/rest/data/@permission/Developer?@fields=realname&roles=Users&@verbose=2' | |
| 1370 | |
| 1368 produces output similar to:: | 1371 produces output similar to:: |
| 1369 | 1372 |
| 1370 { | 1373 { |
| 1371 "data": { | 1374 "data": { |
| 1372 "collection": [ | 1375 "collection": [ |
| 1380 "@total_size": 1 | 1383 "@total_size": 1 |
| 1381 } | 1384 } |
| 1382 } | 1385 } |
| 1383 | 1386 |
| 1384 assuming user 4 is the only user with the Developer role. Note that | 1387 assuming user 4 is the only user with the Developer role. Note that |
| 1385 the url passes the `roles=User` filter option which is silently | 1388 the url passes the ``roles=User`` filter option which is silently |
| 1386 ignored. | 1389 ignored. |
| 1387 | 1390 |
| 1388 Changing Access Roles with JSON Web Tokens | 1391 Changing Access Roles with JSON Web Tokens |
| 1389 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | 1392 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 1390 | 1393 |
| 1399 username and credentials. Especially if your roundup instance is under | 1402 username and credentials. Especially if your roundup instance is under |
| 1400 your company's single sign on infrastructure. | 1403 your company's single sign on infrastructure. |
| 1401 | 1404 |
| 1402 So what we need is a way for this third part service to impersonate | 1405 So what we need is a way for this third part service to impersonate |
| 1403 you and have access to create a roundup timelog entry (see | 1406 you and have access to create a roundup timelog entry (see |
| 1404 `<customizing.html#adding-a-time-log-to-your-issues>`__). Then add it | 1407 `<customizing.html#adding-a-time-log-to-your-issues>`__ ). Then add it |
| 1405 to the associated issue. This should happen without sharing passwords | 1408 to the associated issue. This should happen without sharing passwords |
| 1406 and without the third party service to see the issue (except the | 1409 and without the third party service to see the issue (except the |
| 1407 ``times`` property), user, or other information in the tracker. | 1410 ``times`` property), user, or other information in the tracker. |
| 1408 | 1411 |
| 1409 Enter the use of a JSON web token. Roundup has rudimentary ability to | 1412 Enter the use of a JSON web token. Roundup has rudimentary ability to |
| 1700 the defaults from ``config.ini`` file are used. | 1703 the defaults from ``config.ini`` file are used. |
| 1701 | 1704 |
| 1702 Test Examples | 1705 Test Examples |
| 1703 ^^^^^^^^^^^^^ | 1706 ^^^^^^^^^^^^^ |
| 1704 | 1707 |
| 1705 Rate limit tests: | 1708 Rate limit tests:: |
| 1706 | 1709 |
| 1707 seq 1 300 | xargs -P 20 -n 1 curl --head -si \ | 1710 seq 1 300 | xargs -P 20 -n 1 curl --head -si \ |
| 1708 https://.../rest/data/status/new \# | grep Remaining | 1711 https://.../rest/data/status/new \# | grep Remaining |