Mercurial > p > roundup > code
comparison doc/rest.txt @ 5898:be8524335bfa
Document exact match; Transitive search
Document other string matching modes using := (exact case-sensitive including spaces),
~= substring case-insensitive match. issue?messages.author=1 will find issues
where one or more messages was authored by admin.
| author | John Rouillard <rouilj@ieee.org> |
|---|---|
| date | Sat, 05 Oct 2019 12:46:03 -0400 |
| parents | a8df94ec8040 |
| children | a592e3156134 |
comparison
equal
deleted
inserted
replaced
| 5897:d0aebd4aec72 | 5898:be8524335bfa |
|---|---|
| 332 name is a string, in this case it is also a key value. As a result it | 332 name is a string, in this case it is also a key value. As a result it |
| 333 only does an exact match. | 333 only does an exact match. |
| 334 | 334 |
| 335 Searching for strings (e.g. the issue title, or a keyword name) | 335 Searching for strings (e.g. the issue title, or a keyword name) |
| 336 performs a case-insensitive substring search, so searching for | 336 performs a case-insensitive substring search, so searching for |
| 337 title=Something will find all issues with "Something" or "someThing", | 337 ``title=Something`` (or in long form title~=Something) will find all |
| 338 etc. in the title. There is currently no way to perform an exact | 338 issues with "Something" or "someThing", etc. in the title. Changing |
| 339 string match. | 339 the search to ``title:=Something`` (note the `:`) an exact |
| 340 case-sensitive string match for exactly one word ``Something`` with a | |
| 341 capital ``S``. Another example is: | |
| 342 ``title:=test+that+nosy+actually+works.`` where the + signs are spaces | |
| 343 in the string. Replacing `+` with the `URL encoding`_ for space | |
| 344 ``%20`` will also work. Note that you must match the spaces when | |
| 345 performing exact matches. So `title:=test++that+nosy+actually+works.`` | |
| 346 matches the word test with two spaces after ``test`` in the title. | |
| 340 | 347 |
| 341 To make this clear, searching | 348 To make this clear, searching |
| 342 ``https://.../rest/data/issue?keyword=foo`` will not work unless there | 349 ``https://.../rest/data/issue?keyword=Foo`` will not work unless there |
| 343 is a keyword with a name field of ``foo`` which is the key field of | 350 is a keyword with a (case sensitive) name field of ``Foo`` which is |
| 344 the keyword. However searching the text property ``name`` using | 351 the key field of the keyword. However searching the text property |
| 345 ``https://.../rest/data/keyword?name=foo`` (note searching keyword | 352 ``name`` using ``https://.../rest/data/keyword?name=Foo`` (note |
| 346 class not issue class) will return matches for ``foo``, ``foobar``, | 353 searching keyword class not issue class) will return matches for |
| 347 ``foo taz`` etc. | 354 ``Foo``, ``foobar``, ``foo taz`` etc. |
| 348 | 355 |
| 349 In all cases the field ``@total_size`` is reported which is the total | 356 In all cases the field ``@total_size`` is reported which is the total |
| 350 number of items available if you were to retrieve all of them. | 357 number of items available if you were to retrieve all of them. |
| 351 | 358 |
| 352 Other data types: Date, Interval Integer, Number need examples and may | 359 Other data types: Date, Interval Integer, Number need examples and may |
| 353 need work to allow range searches. Full text search (e.g. over the | 360 need work to allow range searches. Full text search (e.g. over the |
| 354 body of msgs) is a work in progress. | 361 body of a msg) is a work in progress. |
| 362 | |
| 363 .. _URL Encoding: https://en.wikipedia.org/wiki/Percent-encoding | |
| 364 | |
| 365 Transitive Searching | |
| 366 ~~~~~~~~~~~~~~~~~~~~ | |
| 367 | |
| 368 In addition to searching an issue by its properties, you can search | |
| 369 for issues where linked items have a certain property. For example | |
| 370 using ``/issues?messages.author=1`` will find all issues that include | |
| 371 (link to) a message created by the admin user. This can also be done | |
| 372 using: ``/issues?messages.author=admin``. Note that this requires | |
| 373 search permission for messages.author, user.id, and users.username (to | |
| 374 perform search with ``admin``. If these search permissions are not | |
| 375 present, the search will silently drop the attribute. | |
| 376 | |
| 377 Similarly you can find all issues where the nosy list includes James | |
| 378 Bond with: ``issue?nosy.realname=james+bond``. The alternate way to | |
| 379 perform this is to query the user class for the realname: | |
| 380 ``user?realname=james+bond`` and retrieve the id. Then you can execute | |
| 381 a second rest call ``issue?nosy=7`` to retrieve issues with id 7. | |
| 382 | |
| 383 Make sure that search access to the class/properties are granted to the | |
| 384 user. Note that users can search a field even if they can't view | |
| 385 it. However they may be able to use searches to discover the value of | |
| 386 the field even if they can't view it. | |
| 355 | 387 |
| 356 Sorting | 388 Sorting |
| 357 ^^^^^^^ | 389 ^^^^^^^ |
| 358 | 390 |
| 359 Collection endpoints support sorting. This is controlled by specifying a | 391 Collection endpoints support sorting. This is controlled by specifying a |
| 1425 ``Support for jwt disabled by admin.`` if it's not long enough.) | 1457 ``Support for jwt disabled by admin.`` if it's not long enough.) |
| 1426 5. add an auditor to make sure that users with this role are appending | 1458 5. add an auditor to make sure that users with this role are appending |
| 1427 timelog links to the ``times`` property of the issue. | 1459 timelog links to the ``times`` property of the issue. |
| 1428 | 1460 |
| 1429 Create role | 1461 Create role |
| 1430 """"""""""" | 1462 ~~~~~~~~~~~ |
| 1431 | 1463 |
| 1432 Adding this snippet of code to the tracker's ``schema.py`` should create a role with the | 1464 Adding this snippet of code to the tracker's ``schema.py`` should create a role with the |
| 1433 proper authorization:: | 1465 proper authorization:: |
| 1434 | 1466 |
| 1435 db.security.addRole(name="User:timelog", | 1467 db.security.addRole(name="User:timelog", |
| 1471 Note that the json returned after the operation will include the new | 1503 Note that the json returned after the operation will include the new |
| 1472 value of the ``times`` value so your code can verify that it worked. | 1504 value of the ``times`` value so your code can verify that it worked. |
| 1473 This does potentially leak info about the previous id's in the field. | 1505 This does potentially leak info about the previous id's in the field. |
| 1474 | 1506 |
| 1475 Create rest endpoints | 1507 Create rest endpoints |
| 1476 """"""""""""""""""""" | 1508 ~~~~~~~~~~~~~~~~~~~~~ |
| 1477 | 1509 |
| 1478 Here is code to add to your tracker's ``interfaces.py`` (note code has | 1510 Here is code to add to your tracker's ``interfaces.py`` (note code has |
| 1479 only been tested with python3):: | 1511 only been tested with python3):: |
| 1480 | 1512 |
| 1481 from roundup.rest import Routing, RestfulInstance, _data_decorator | 1513 from roundup.rest import Routing, RestfulInstance, _data_decorator |