Mercurial > p > roundup > code
comparison doc/rest.txt @ 5663:a884698173ea
Document searching and @verbose attribute
| author | Ralf Schlatterbeck <rsc@runtux.com> |
|---|---|
| date | Fri, 22 Mar 2019 14:43:21 +0100 |
| parents | d8d2b7724292 |
| children | 6dc4dba1c225 |
comparison
equal
deleted
inserted
replaced
| 5662:5ceed592706e | 5663:a884698173ea |
|---|---|
| 56 ``/data/issue/42/title``. | 56 ``/data/issue/42/title``. |
| 57 | 57 |
| 58 When performing the ``GET`` method on a class (e.g. ``/data/issue``), the | 58 When performing the ``GET`` method on a class (e.g. ``/data/issue``), the |
| 59 number of items is returned in ``@total_size``. Then a ``collection`` | 59 number of items is returned in ``@total_size``. Then a ``collection`` |
| 60 list follows which contains the id and link to the respective item. | 60 list follows which contains the id and link to the respective item. |
| 61 This endpoint supports pagination. With the attributes @page_size and | |
| 62 @page_index, pagination is controlled. The @page_size specifies how many | |
| 63 items are displayed at once. The @page_index (which defaults to 1 if not | |
| 64 given) specifies which page number of @page_size items is displayed. If | |
| 65 no @page_size is specified, all items are returned. | |
| 66 In addition this method supports searching. Search parameters are names | |
| 67 of properties of the given class, e.g., ``status`` for ``issue``. Links | |
| 68 and Multilinks can be specified numerically or symbolically, e.g., | |
| 69 searching for issues in status ``closed`` can be achieved by searching | |
| 70 for ``status=closed`` or ``status=3`` (provided the ``closed`` status | |
| 71 has ID 3). Note that searching for strings (e.g. the issue title) | |
| 72 performs a case-insensitive substring search, so searching for | |
| 73 title=Something will find all issues with "Something" or "someThing", | |
| 74 etc. in the title. There is currently no way to perform an exact string | |
| 75 match. | |
| 61 | 76 |
| 62 When performing the ``GET`` method on an item (e.g. ``/data/issue/42``), a | 77 When performing the ``GET`` method on an item (e.g. ``/data/issue/42``), a |
| 63 ``link`` attribute contains the link to the item, ``id`` contains the | 78 ``link`` attribute contains the link to the item, ``id`` contains the |
| 64 id, type contains the class name (e.g. ``issue`` in the example) and an | 79 id, type contains the class name (e.g. ``issue`` in the example) and an |
| 65 ``etag`` property can be used to detect modifications since the last | 80 ``etag`` property can be used to detect modifications since the last |
| 66 query. The individual properties of the item are returned in an | 81 query. The individual properties of the item are returned in an |
| 67 ``attributes`` dictionary. The properties returned depend on the | 82 ``attributes`` dictionary. The properties returned depend on the |
| 68 permissions of the account used for the query. | 83 permissions of the account used for the query. |
| 84 Link and Multilink properties are displayed as a dictionary with a link | |
| 85 and an id property by default. This is controlled by the @verbose | |
| 86 attribute which is set to 1 by default. If set to 0, only the id is | |
| 87 shown for Link and Multilink attributes. If set to 2, the label property | |
| 88 (usually ``name`` e.g. for status) is also put into the dictionary. | |
| 89 Content properties of message and file object are by default also shown | |
| 90 as a dictionary with a sole link attribute. The link is the download | |
| 91 link for the file or message. If @verbose is >= 3, the content property | |
| 92 is shown in json as a (possibly very long) string. Currently the json | |
| 93 serializer cannot handle files not properly utf-8 encoded, so specifying | |
| 94 @verbose=3 for files is currently discouraged. | |
| 69 | 95 |
| 70 A ``GET`` method on a property (e.g. ``/data/issue/42/title``) returns the | 96 A ``GET`` method on a property (e.g. ``/data/issue/42/title``) returns the |
| 71 link, an ``@etag``, the type of the property (e.g. "<type str>") the id | 97 link, an ``@etag``, the type of the property (e.g. "<type str>") the id |
| 72 of the item and the content of the property in ``data``. | 98 of the item and the content of the property in ``data``. |
| 73 | 99 |