Mercurial > p > roundup > code

annotate doc/rest.txt @ 5696:b67636bc87d0

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add CSRF protection to rest code path. Follow same model as for xmlrpc. The original rest code was developed before the CSRF code was added to xmlrpc.
author John Rouillard <rouilj@ieee.org>
date Sun, 07 Apr 2019 20:27:25 -0400
parents 3e1b66c4e1e2
children c7dd1cae3416
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
1
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
2 ====================
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
3 REST API for Roundup
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
4 ====================
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
5
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
6 .. contents::
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
7 :local:
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
8
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
9 Introduction
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
10 ------------
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
11
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
12 After the last 1.6.0 Release, a REST-API developed in 2015 during a Google
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
13 Summer of Code (GSOC) by Chau Nguyen, supervised by Ezio Melotti was
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
14 integrated. The code was then updated by John Rouillard and Ralf
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
15 Schlatterbeck to fix some shortcomings and provide the necessary
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
16 functions for a single page web application, e.g. etag support among
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
17 others.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
18
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
19 Enabling the REST API
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
20 ---------------------
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
21
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
22 The REST API can be disabled in the ``[web]`` section of ``config.ini``
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
23 via the variable ``enable_rest`` which is ``yes`` by default.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
24
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
25 The REST api is reached via the ``/rest/`` endpoint of the tracker URL.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
26
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
27
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
28 Client API
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
29 ----------
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
30
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
31 The top-level REST url ``/rest/`` will display the current version of
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
32 the REST API (Version 1 as of this writing) and some links to relevant
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
33 endpoints of the API. In the following the ``/rest`` prefix is ommitted
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
34 from relative REST-API links for brevety.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
35
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
36 Summary
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
37 =======
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
38
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
39 A Summary page can be reached via ``/summary`` via the ``GET`` method.
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
40 This is currently hard-coded for the standard tracker schema shipped
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
41 with roundup and will display a summary of open issues.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
42
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
43 Data
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
44 ====
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
45
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
46 All the links mentioned in the following support the http method ``GET``.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
47 Results of a ``GET`` request will always return the results as a
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
48 dictionary with the entry ``data`` referring to the returned data.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
49
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
50 The ``/data`` link will display a set of classes of the tracker. All
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
51 classes can be reached via ``/data/<classname>`` where ``<classname>``
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
52 is replace with the name of the class to query, e.g. ``/data/issue``.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
53 Individual items of a class (e.g. a single issue) can be queried by
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
54 giving the issue-id, e.g., ``/data/issue/42``. Individual properties of
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
55 an item can be queried by appending the property, e.g.,
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
56 ``/data/issue/42/title``.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
57
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
58 When performing the ``GET`` method on a class (e.g. ``/data/issue``), the
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
59 number of items is returned in ``@total_size``. Then a ``collection``
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
60 list follows which contains the id and link to the respective item.
5663
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
61 This endpoint supports pagination. With the attributes @page_size and
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
62 @page_index, pagination is controlled. The @page_size specifies how many
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
63 items are displayed at once. The @page_index (which defaults to 1 if not
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
64 given) specifies which page number of @page_size items is displayed. If
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
65 no @page_size is specified, all items are returned.
5677
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
66
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
67 Adding the query parameter @verbose=2 to the GET will include the label
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
68 property in addition to id and link for the items. This is useful as
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
69 documented below in "Searches and selection".
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
70
5663
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
71 In addition this method supports searching. Search parameters are names
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
72 of properties of the given class, e.g., ``status`` for ``issue``. Links
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
73 and Multilinks can be specified numerically or symbolically, e.g.,
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
74 searching for issues in status ``closed`` can be achieved by searching
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
75 for ``status=closed`` or ``status=3`` (provided the ``closed`` status
5677
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
76 has ID 3). Note that searching for strings (e.g. the issue title, or a
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
77 keyword name) performs a case-insensitive substring search, so searching
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
78 for title=Something will find all issues with "Something" or "someThing",
5663
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
79 etc. in the title. There is currently no way to perform an exact string
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
80 match.
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
81
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
82 When performing the ``GET`` method on an item (e.g. ``/data/issue/42``), a
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
83 ``link`` attribute contains the link to the item, ``id`` contains the
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
84 id, type contains the class name (e.g. ``issue`` in the example) and an
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
85 ``etag`` property can be used to detect modifications since the last
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
86 query. The individual properties of the item are returned in an
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
87 ``attributes`` dictionary. The properties returned depend on the
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
88 permissions of the account used for the query.
5663
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
89 Link and Multilink properties are displayed as a dictionary with a link
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
90 and an id property by default. This is controlled by the @verbose
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
91 attribute which is set to 1 by default. If set to 0, only the id is
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
92 shown for Link and Multilink attributes. If set to 2, the label property
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
93 (usually ``name`` e.g. for status) is also put into the dictionary.
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
94 Content properties of message and file object are by default also shown
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
95 as a dictionary with a sole link attribute. The link is the download
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
96 link for the file or message. If @verbose is >= 3, the content property
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
97 is shown in json as a (possibly very long) string. Currently the json
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
98 serializer cannot handle files not properly utf-8 encoded, so specifying
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
99 @verbose=3 for files is currently discouraged.
5678
b8e8b1b3ec77 REST: Add key lookup
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5677
diff changeset
100 Note that if the class has a key attribute (like e.g., the 'status'
b8e8b1b3ec77 REST: Add key lookup
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5677
diff changeset
101 class in the classic tracker), you can get an individual status by
b8e8b1b3ec77 REST: Add key lookup
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5677
diff changeset
102 specifying the key-attribute e.g. ``/data/status/name=closed``. Note
b8e8b1b3ec77 REST: Add key lookup
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5677
diff changeset
103 that ``name`` in this example must be the key-attribute of the class.
b8e8b1b3ec77 REST: Add key lookup
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5677
diff changeset
104 A short-form (which might no longer be supported in future version of
b8e8b1b3ec77 REST: Add key lookup
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5677
diff changeset
105 the API) is to specify only the value, e.g. ``/data/status/closed``.
b8e8b1b3ec77 REST: Add key lookup
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5677
diff changeset
106 This short-form only works when you're sure that the key of the class is
b8e8b1b3ec77 REST: Add key lookup
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5677
diff changeset
107 not numeric.
b8e8b1b3ec77 REST: Add key lookup
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5677
diff changeset
108 The long-form (with ``=``) is different from a query-parameter like
b8e8b1b3ec77 REST: Add key lookup
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5677
diff changeset
109 ``/data/status?@name=closed`` which would find all stati that have
b8e8b1b3ec77 REST: Add key lookup
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5677
diff changeset
110 ``closed`` as a substring.
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
111
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
112 A ``GET`` method on a property (e.g. ``/data/issue/42/title``) returns the
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
113 link, an ``@etag``, the type of the property (e.g. "<type str>") the id
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
114 of the item and the content of the property in ``data``.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
115
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
116 Only class links support the ``POST`` method for creation of new items
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
117 of a class, e.g., a new issue via the ``/data/issue`` link. The post
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
118 gets a dictionary of keys/values for the new item. It returns the same
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
119 parameters as the GET method after successful creation.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
120
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
121 All endpoints support an ``OPTIONS`` method for determining which
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
122 methods are allowed on a given endpoint.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
123
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
124 The method ``PUT`` is allowed on individual items, e.g.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
125 ``/data/issue/42`` as well as properties, e.g.,
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
126 ``/data/issue/42/title``. On success it returns the same parameters as
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
127 the respective ``GET`` method. Note that for ``PUT`` an Etag has to be
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
128 supplied, either in the request header or as an @etag parameter.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
129
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
130 The method ``DELETE`` is allowed on items, e.g., ``/data/issue/42`` and
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
131 will retire (mark as deleted) the respective item. On success it will
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
132 only return a status code. It is also possible to call ``DELETE`` on a
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
133 property of an item, e.g., ``/data/issue/42/nosy`` to delete the nosy
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
134 list. The same effect can be achieved with a ``PUT`` request and an
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
135 empty new value.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
136
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
137 Finally the ``PATCH`` method can be applied to individual items, e.g.,
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
138 ``/data/issue/42`` and to properties, e.g., ``/data/issue/42/title``.
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
139 This method gets an operator ``@op=<method>`` where ``<method>`` is one
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
140 of ``add``, ``replace``, ``remove``, only for an item (not for a
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
141 property) an additional operator ``action`` is supported. If no operator
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
142 is specified, the default is ``replace``. The first three operators are
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
143 self explanatory. For an ``action`` operator an ``@action_name`` and
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
144 optional ``@action_argsXXX`` parameters have to be supplied. Currently
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
145 there are only two actions, neither has args, namely ``retire`` and
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
146 ``restore``. The ``retire`` action on an item is the same as a
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
147 ``DELETE`` method, it retires the item. The ``restore`` action is the
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
148 inverse of ``retire``, the item is again visible.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
149 On success the returned value is the same as the respective ``GET``
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
150 method.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
151
5674
6dc4dba1c225 REST: Use If-Match header for incoming requests
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5663
diff changeset
152 Note that the ``GET`` method on an item (e.g. ``/data/issue/43``)
6dc4dba1c225 REST: Use If-Match header for incoming requests
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5663
diff changeset
153 returns an ETag in the http header *and* the ``@etag`` value. When
6dc4dba1c225 REST: Use If-Match header for incoming requests
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5663
diff changeset
154 modifying the item via ``PUT`` or ``PATCH`` either a ``If-Match`` header
6dc4dba1c225 REST: Use If-Match header for incoming requests
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5663
diff changeset
155 or an ``@etag`` value in the form have to be provided.
6dc4dba1c225 REST: Use If-Match header for incoming requests
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5663
diff changeset
156
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
157 sample python client
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
158 ====================
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
159
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
160 The client uses the python ``requests`` library for easier interaction
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
161 with a REST API supporting JSON encoding::
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
162
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
163
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
164 >>> import requests
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
165 >>> u = 'http://user:password@tracker.example.com/demo/rest/data/'
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
166 >>> s = requests.session()
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
167 >>> r = s.get(u + 'issue/42/title')
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
168 >>> if r.status_code != 200:
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
169 ... print("Failed: %s: %s" % (r.status_code, r.reason))
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
170 ... exit(1)
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
171 >>> print (r.json() ['data']['data']
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
172 TEST Title
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
173 >>> r = s.post (u + 'issue', data = dict (title = 'TEST Issue'))
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
174 >>> if not 200 <= r.status_code <= 201:
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
175 ... print("Failed: %s: %s" % (r.status_code, r.reason))
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
176 ... exit(1)
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
177 >>> print(r.json())
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
178
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
179 Retire/Restore::
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
180 >>> r = s.delete (u + 'issue/42')
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
181 >>> print (r.json())
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
182 >>> r = s.get (u + 'issue/42')
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
183 >>> etag = r.headers['ETag']
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
184 >>> print("ETag: %s" % etag)
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
185 >>> etag = r.json()['data']['@etag']
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
186 >>> print("@etag: %s" % etag)
5674
6dc4dba1c225 REST: Use If-Match header for incoming requests
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5663
diff changeset
187 >>> h = {'If-Match': etag}
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
188 >>> d = {'@op:'action', '@action_name':'retire'}
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
189 >>> r = s.patch(u + 'issue/42', data = d, headers = h)
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
190 >>> print(r.json())
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
191 >>> d = {'@op:'action', '@action_name':'restore'}
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
192 >>> r = s.patch(u + 'issue/42', data = d, headers = h)
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
193 >>> print(r.json())
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
194
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
195 Adding new rest endpoints
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
196 =========================
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
197
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
198 Add or edit the file interfaces.py at the root of the tracker
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
199 directory.
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
200
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
201 In that file add::
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
202
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
203 from roundup.rest import Routing, RestfulInstance, _data_decorator
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
204 from roundup.exceptions import Unauthorised
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
205
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
206 class RestfulInstance:
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
207
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
208 @Routing.route("/summary2")
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
209 @_data_decorator
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
210 def summary2(self, input):
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
211 result = { "hello": "world" }
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
212 return 200, result
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
213
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
214 will make a new endpoint .../rest/summary2 that you can test with::
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
215
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
216 $ curl -X GET .../rest/summary2
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
217 {
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
218 "data": {
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
219 "hello": "world"
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
220 }
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
221 }
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
222
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
223 Similarly appending this to interfaces.py after summary2::
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
224
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
225 # handle more endpoints
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
226 @Routing.route("/data/<:class_name>/@schema", 'GET')
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
227 def get_element_schema(self, class_name, input):
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
228 result = { "schema": {} }
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
229 uid = self.db.getuid ()
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
230 if not self.db.security.hasPermission('View', uid, class_name) :
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
231 raise Unauthorised('Permission to view %s denied' % class_name)
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
232
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
233 class_obj = self.db.getclass(class_name)
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
234 props = class_obj.getprops(protected=False)
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
235 schema = result['schema']
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
236
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
237 for prop in props:
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
238 schema[prop] = { "type": repr(class_obj.properties[prop]) }
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
239
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
240 return result
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
241
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
242 ..
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
243 the # comment in the example is needed to preserve indention under Class.
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
244
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
245 returns some data about the class::
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
246
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
247 $ curl -X GET .../rest/data/issue/@schema
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
248 {
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
249 "schema": {
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
250 "keyword": {
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
251 "type": "<roundup.hyperdb.Multilink to \"keyword\">"
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
252 },
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
253 "title": {
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
254 "type": "<roundup.hyperdb.String>"
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
255 },
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
256 "files": {
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
257 "type": "<roundup.hyperdb.Multilink to \"file\">"
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
258 },
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
259 "status": {
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
260 "type": "<roundup.hyperdb.Link to \"status\">"
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
261 }, ...
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
262 }
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
263 }
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
264
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
265
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
266 Adding other endpoints (e.g. to allow an OPTIONS query against
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
267 ``/data/issue/@schema``) is left as an exercise for the reader.
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
268
5677
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
269 Searches and selection
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
270 ======================
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
271
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
272 One difficult interface issue is selection of items from a long list.
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
273 Using multi-item selects requires loading a lot of data (e.g. consider
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
274 a selection tool to select one or more issues as in the classic
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
275 superseder field).
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
276
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
277 This can be made easier using javascript selection tools like select2,
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
278 selectize.js, chosen etc. These tools can query a remote data provider
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
279 to get a list of items for the user to select from.
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
280
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
281 Consider a multi-select box for the superseder property. Using
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
282 selectize.js (and jquery) code similar to::
5677
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
283
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
284 $('#superseder').selectize({
5677
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
285 valueField: 'id',
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
286 labelField: 'title',
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
287 searchField: 'title', ...
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
288 load: function(query, callback) {
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
289 if (!query.length) return callback();
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
290 $.ajax({
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
291 url: '.../rest/data/issue?@verbose=2&title='
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
292 + encodeURIComponent(query),
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
293 type: 'GET',
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
294 error: function() {callback();},
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
295 success: function(res) {
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
296 callback(res.data.collection);}
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
297
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
298 Sets up a box that a user can type the word "request" into. Then
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
299 selectize.js will use that word to generate an ajax request with the
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
300 url: ``.../rest/data/issue?@verbose=2&title=request``
5677
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
301
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
302 This will return data like::
5677
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
303
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
304 {
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
305 "data": {
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
306 "@total_size": 440,
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
307 "collection": [
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
308 {
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
309 "link": ".../rest/data/issue/8",
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
310 "id": "8",
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
311 "title": "Request for Power plugs"
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
312 },
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
313 {
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
314 "link": ".../rest/data/issue/27",
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
315 "id": "27",
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
316 "title": "Request for foo"
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
317 },
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
318 ...
5677
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
319
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
320 selectize.js will look at these objects (as passed to
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
321 callback(res.data.collection)) and create a select list from the each
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
322 object showing the user the labelField (title) for each object and
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
323 associating each title with the corresponding valueField (id). The
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
324 example above has 440 issues returned from a total of 2000
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
325 issues. Only 440 had the word "request" somewhere in the title greatly
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
326 reducing the amount of data that needed to be transferred.
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
327
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
328 Similar code can be set up to search a large list of keywords using::
5677
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
329
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
330 .../rest/data/keyword?@verbose=2&name=some
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
331
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
332 which would return: "some keyword" "awesome" "somebody" making
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
333 selections for links and multilinks much easier.
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
334
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
335 Hopefully future enhancements will allow get on a collection to
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
336 include other fields. Why do we want this? Selectize.js can set up
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
337 option groups (optgroups) in the select pulldown. So by including
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
338 status in the returned data::
5677
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
339
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
340 {
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
341 "link": ".../rest/data/issue/27",
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
342 "id": "27",
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
343 "title": "Request for foo",
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
344 'status": "open"
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
345 },
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
346
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
347 a select widget like::
5677
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
348
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
349 === New ===
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
350 A request
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
351 === Open ===
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
352 Request for bar
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
353 Request for foo
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
354
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
355 etc. can be generated. Also depending on the javascript library, other
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
356 fields can be used for subsearch and sorting.
Roundup Issue Tracker: http://roundup-tracker.org/