Mercurial > p > roundup > code
annotate doc/rest.txt @ 5705:457fc482e6b1
Method PUT: ignore specification of protected properties which can not
be set. Filtering them out of the payload list. This lets the result
of a get using:
class/id?@protected=true&@verbose=0
be used as input to a PUT operation without having to strip the
protected properties.
Note this does not raise an error if the PUT protected property is
different from the value in the db. If the property is different but
the etag/if-match passes, the user attempted to set the protected
property and this should result in an error, but will not with this
patch.
Method DELETE class/id/attribute: raise error when trying to delete
protected or required attribute/property. Raise UsageError
when attribute doesn't exist.
Method PATCH class/id:
raise error when trying to replace/remove protected attribute/property
raise error when trying to remove required attribute/property
Catch KeyError at top level and turn into 400 error.
If payload has an attribute/property that does not exist, raise
UsageError which becomes a 400 error.
| author | John Rouillard <rouilj@ieee.org> |
|---|---|
| date | Thu, 11 Apr 2019 20:54:39 -0400 |
| parents | c7dd1cae3416 |
| children | 0b79bfcb3312 |
| 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 | 100 Note that if the class has a key attribute (like e.g., the 'status' |
| 101 class in the classic tracker), you can get an individual status by | |
| 102 specifying the key-attribute e.g. ``/data/status/name=closed``. Note | |
| 103 that ``name`` in this example must be the key-attribute of the class. | |
| 104 A short-form (which might no longer be supported in future version of | |
| 105 the API) is to specify only the value, e.g. ``/data/status/closed``. | |
| 106 This short-form only works when you're sure that the key of the class is | |
| 107 not numeric. | |
| 108 The long-form (with ``=``) is different from a query-parameter like | |
| 109 ``/data/status?@name=closed`` which would find all stati that have | |
| 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 |
|
5698
c7dd1cae3416
Update rest.txt example to include headers required for CSRF
John Rouillard <rouilj@ieee.org>
parents:
5695
diff
changeset
|
173 >>> h = {'X-Requested-With': 'rest', 'Referer': 'http://tracker.example.com/demo/'} |
|
c7dd1cae3416
Update rest.txt example to include headers required for CSRF
John Rouillard <rouilj@ieee.org>
parents:
5695
diff
changeset
|
174 >>> r = s.post (u + 'issue', data = dict (title = 'TEST Issue'), headers=h) |
|
5660
d8d2b7724292
First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff
changeset
|
175 >>> if not 200 <= r.status_code <= 201: |
|
d8d2b7724292
First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff
changeset
|
176 ... print("Failed: %s: %s" % (r.status_code, r.reason)) |
|
d8d2b7724292
First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff
changeset
|
177 ... exit(1) |
|
d8d2b7724292
First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff
changeset
|
178 >>> print(r.json()) |
|
d8d2b7724292
First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff
changeset
|
179 |
|
d8d2b7724292
First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff
changeset
|
180 Retire/Restore:: |
|
d8d2b7724292
First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff
changeset
|
181 >>> r = s.delete (u + 'issue/42') |
|
d8d2b7724292
First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff
changeset
|
182 >>> print (r.json()) |
|
d8d2b7724292
First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff
changeset
|
183 >>> r = s.get (u + 'issue/42') |
|
d8d2b7724292
First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff
changeset
|
184 >>> etag = r.headers['ETag'] |
|
d8d2b7724292
First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff
changeset
|
185 >>> print("ETag: %s" % etag) |
|
d8d2b7724292
First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff
changeset
|
186 >>> etag = r.json()['data']['@etag'] |
|
d8d2b7724292
First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff
changeset
|
187 >>> print("@etag: %s" % etag) |
|
5698
c7dd1cae3416
Update rest.txt example to include headers required for CSRF
John Rouillard <rouilj@ieee.org>
parents:
5695
diff
changeset
|
188 >>> h = {'If-Match': etag, 'X-Requested-With': 'rest', 'Referer': 'http://tracker.example.com/demo/'} |
|
5660
d8d2b7724292
First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff
changeset
|
189 >>> d = {'@op:'action', '@action_name':'retire'} |
|
d8d2b7724292
First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff
changeset
|
190 >>> 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
|
191 >>> print(r.json()) |
|
d8d2b7724292
First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff
changeset
|
192 >>> d = {'@op:'action', '@action_name':'restore'} |
|
d8d2b7724292
First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff
changeset
|
193 >>> 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
|
194 >>> print(r.json()) |
|
d8d2b7724292
First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff
changeset
|
195 |
|
5698
c7dd1cae3416
Update rest.txt example to include headers required for CSRF
John Rouillard <rouilj@ieee.org>
parents:
5695
diff
changeset
|
196 Note the addition of headers for: x-requested-with and referer. This |
|
c7dd1cae3416
Update rest.txt example to include headers required for CSRF
John Rouillard <rouilj@ieee.org>
parents:
5695
diff
changeset
|
197 allows the request to pass the CSRF protection mechanism. You may need |
|
c7dd1cae3416
Update rest.txt example to include headers required for CSRF
John Rouillard <rouilj@ieee.org>
parents:
5695
diff
changeset
|
198 to add Origin if this check is enabled in your tracker's config.ini. |
|
c7dd1cae3416
Update rest.txt example to include headers required for CSRF
John Rouillard <rouilj@ieee.org>
parents:
5695
diff
changeset
|
199 |
|
c7dd1cae3416
Update rest.txt example to include headers required for CSRF
John Rouillard <rouilj@ieee.org>
parents:
5695
diff
changeset
|
200 |
|
5688
1b9ef04b9528
Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents:
5678
diff
changeset
|
201 Adding new rest endpoints |
|
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 |
|
1b9ef04b9528
Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents:
5678
diff
changeset
|
204 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
|
205 directory. |
|
1b9ef04b9528
Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents:
5678
diff
changeset
|
206 |
|
5695
3e1b66c4e1e2
Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents:
5688
diff
changeset
|
207 In that file add:: |
|
5688
1b9ef04b9528
Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents:
5678
diff
changeset
|
208 |
|
1b9ef04b9528
Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents:
5678
diff
changeset
|
209 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
|
210 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
|
211 |
|
1b9ef04b9528
Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents:
5678
diff
changeset
|
212 class RestfulInstance: |
|
1b9ef04b9528
Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents:
5678
diff
changeset
|
213 |
|
1b9ef04b9528
Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents:
5678
diff
changeset
|
214 @Routing.route("/summary2") |
|
1b9ef04b9528
Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents:
5678
diff
changeset
|
215 @_data_decorator |
|
1b9ef04b9528
Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents:
5678
diff
changeset
|
216 def summary2(self, input): |
|
1b9ef04b9528
Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents:
5678
diff
changeset
|
217 result = { "hello": "world" } |
|
1b9ef04b9528
Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents:
5678
diff
changeset
|
218 return 200, result |
|
1b9ef04b9528
Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents:
5678
diff
changeset
|
219 |
|
5695
3e1b66c4e1e2
Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents:
5688
diff
changeset
|
220 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
|
221 |
|
1b9ef04b9528
Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents:
5678
diff
changeset
|
222 $ curl -X GET .../rest/summary2 |
|
1b9ef04b9528
Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents:
5678
diff
changeset
|
223 { |
|
1b9ef04b9528
Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents:
5678
diff
changeset
|
224 "data": { |
|
1b9ef04b9528
Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents:
5678
diff
changeset
|
225 "hello": "world" |
|
1b9ef04b9528
Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents:
5678
diff
changeset
|
226 } |
|
1b9ef04b9528
Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents:
5678
diff
changeset
|
227 } |
|
1b9ef04b9528
Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents:
5678
diff
changeset
|
228 |
|
5695
3e1b66c4e1e2
Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents:
5688
diff
changeset
|
229 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
|
230 |
|
5695
3e1b66c4e1e2
Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents:
5688
diff
changeset
|
231 # 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
|
232 @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
|
233 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
|
234 result = { "schema": {} } |
|
3e1b66c4e1e2
Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents:
5688
diff
changeset
|
235 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
|
236 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
|
237 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
|
238 |
|
5695
3e1b66c4e1e2
Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents:
5688
diff
changeset
|
239 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
|
240 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
|
241 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
|
242 |
|
3e1b66c4e1e2
Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents:
5688
diff
changeset
|
243 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
|
244 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
|
245 |
|
5695
3e1b66c4e1e2
Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents:
5688
diff
changeset
|
246 return result |
|
5688
1b9ef04b9528
Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents:
5678
diff
changeset
|
247 |
|
5695
3e1b66c4e1e2
Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents:
5688
diff
changeset
|
248 .. |
|
3e1b66c4e1e2
Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents:
5688
diff
changeset
|
249 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
|
250 |
|
5695
3e1b66c4e1e2
Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents:
5688
diff
changeset
|
251 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
|
252 |
|
1b9ef04b9528
Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents:
5678
diff
changeset
|
253 $ 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
|
254 { |
|
1b9ef04b9528
Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents:
5678
diff
changeset
|
255 "schema": { |
|
1b9ef04b9528
Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents:
5678
diff
changeset
|
256 "keyword": { |
|
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 \"keyword\">" |
|
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 "title": { |
|
1b9ef04b9528
Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents:
5678
diff
changeset
|
260 "type": "<roundup.hyperdb.String>" |
|
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 "files": { |
|
1b9ef04b9528
Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents:
5678
diff
changeset
|
263 "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
|
264 }, |
|
1b9ef04b9528
Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents:
5678
diff
changeset
|
265 "status": { |
|
1b9ef04b9528
Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents:
5678
diff
changeset
|
266 "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
|
267 }, ... |
|
1b9ef04b9528
Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents:
5678
diff
changeset
|
268 } |
|
1b9ef04b9528
Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents:
5678
diff
changeset
|
269 } |
|
1b9ef04b9528
Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents:
5678
diff
changeset
|
270 |
|
1b9ef04b9528
Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents:
5678
diff
changeset
|
271 |
|
5695
3e1b66c4e1e2
Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents:
5688
diff
changeset
|
272 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
|
273 ``/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
|
274 |
|
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
|
275 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
|
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 |
|
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 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
|
279 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
|
280 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
|
281 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
|
282 |
|
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 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
|
284 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
|
285 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
|
286 |
|
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 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
|
288 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
|
289 |
|
5695
3e1b66c4e1e2
Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents:
5688
diff
changeset
|
290 $('#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
|
291 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
|
292 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
|
293 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
|
294 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
|
295 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
|
296 $.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
|
297 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
|
298 + 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
|
299 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
|
300 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
|
301 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
|
302 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
|
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 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
|
305 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
|
306 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
|
307 |
|
5695
3e1b66c4e1e2
Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents:
5688
diff
changeset
|
308 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
|
309 |
|
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 { |
|
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 "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
|
312 "@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
|
313 "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
|
314 { |
|
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 "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
|
316 "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
|
317 "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
|
318 }, |
|
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 "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
|
321 "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
|
322 "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
|
323 }, |
|
5695
3e1b66c4e1e2
Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents:
5688
diff
changeset
|
324 ... |
|
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
|
325 |
|
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 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
|
327 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
|
328 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
|
329 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
|
330 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
|
331 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
|
332 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
|
333 |
|
5695
3e1b66c4e1e2
Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents:
5688
diff
changeset
|
334 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
|
335 |
|
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 .../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
|
337 |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
338 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
|
339 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
|
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 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
|
342 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
|
343 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
|
344 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
|
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 { |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
347 "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
|
348 "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
|
349 "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
|
350 '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
|
351 }, |
|
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 |
|
5695
3e1b66c4e1e2
Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents:
5688
diff
changeset
|
353 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
|
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 === 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
|
356 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
|
357 === 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
|
358 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
|
359 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
|
360 |
|
1fa59181ce58
Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents:
5674
diff
changeset
|
361 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
|
362 fields can be used for subsearch and sorting. |
