annotate doc/rest.txt @ 5710:0b79bfcb3312

Add support for making an idempotent POST. This allows retrying a POST that was interrupted. It involves creating a post once only (poe) url /rest/data/<class>/@poe/<random_token>. This url acts the same as a post to /rest/data/<class>. However once the @poe url is used, it can't be used for a second POST. To make these changes: 1) Take the body of post_collection into a new post_collection_inner function. Have post_collection call post_collection_inner. 2) Add a handler for POST to rest/data/class/@poe. This will return a unique POE url. By default the url expires after 30 minutes. The POE random token is only good for a specific user and is stored in the session db. 3) Add a handler for POST to rest/data/<class>/@poe/<random token>. The random token generated in 2 is validated for proper class (if token is not generic) and proper user and must not have expired. If everything is valid, call post_collection_inner to process the input and generate the new entry. To make recognition of 2 stable (so it's not confused with rest/data/<:class_name>/<:item_id>), removed @ from Routing::url_to_regex. The current Routing.execute method stops on the first regular expression to match the URL. Since item_id doesn't accept a POST, I was getting 405 bad method sometimes. My guess is the order of the regular expressions is not stable, so sometime I would get the right regexp for /data/<class>/@poe and sometime I would get the one for /data/<class>/<item_id>. By removing the @ from the url_to_regexp, there was no way for the item_id case to match @poe. There are alternate fixes we may need to look at. If a regexp matches but the method does not, return to the regexp matching loop in execute() looking for another match. Only once every possible match has failed should the code return a 405 method failure. Another fix is to implement a more sophisticated mechanism so that @Routing.route("/data/<:class_name>/<:item_id>/<:attr_name>", 'PATCH') has different regexps for matching <:class_name> <:item_id> and <:attr_name>. Currently the regexp specified by url_to_regex is used for every component. Other fixes: Made failure to find any props in props_from_args return an empty dict rather than throwing an unhandled error. Make __init__ for SimulateFieldStorageFromJson handle an empty json doc. Useful for POSTing to rest/data/class/@poe with an empty document. Testing: added testPostPOE to test/rest_common.py that I think covers all the code that was added. Documentation: Add doc to rest.txt in the "Client API" section titled: Safely Re-sending POST". Move existing section "Adding new rest endpoints" in "Client API" to a new second level section called "Programming the REST API". Also a minor change to the simple rest client moving the header setting to continuation lines rather than showing one long line.
author John Rouillard <rouilj@ieee.org>
date Sun, 14 Apr 2019 21:07:11 -0400
parents c7dd1cae3416
children 59a3bbd3603a
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
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)
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
188 >>> h = {'If-Match': etag,
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
189 ... 'X-Requested-With': 'rest',
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
190 ... 'Referer': 'http://tracker.example.com/demo/'}
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
191 >>> d = {'@op:'action', '@action_name':'retire'}
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 >>> d = {'@op:'action', '@action_name':'restore'}
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
195 >>> 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
196 >>> print(r.json())
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
197
5698
c7dd1cae3416 Update rest.txt example to include headers required for CSRF
John Rouillard <rouilj@ieee.org>
parents: 5695
diff changeset
198 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
199 allows the request to pass the CSRF protection mechanism. You may need
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
200 to add an Origin header if this check is enabled in your tracker's
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
201 config.ini (look for csrf_enforce_header_origin).
5698
c7dd1cae3416 Update rest.txt example to include headers required for CSRF
John Rouillard <rouilj@ieee.org>
parents: 5695
diff changeset
202
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
203 Safely Re-sending POST
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
204 ======================
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
205
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
206 POST is used to create new object in a class. E.G. a new issue. One
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
207 problem is that a POST may time out. Because it is not idempotent like
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
208 a PUT or DELETE, retrying the interrupted POST may result in the
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
209 creation of a duplicate issue.
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
210
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
211 To solve this problem, a two step process inspired by the POE - Post
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
212 Once Exactly spec:
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
213 https://tools.ietf.org/html/draft-nottingham-http-poe-00 is provided.
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
214
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
215 This mechanism returns a single use URL. POSTing to the URL creates
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
216 a new object in the class.
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
217
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
218 First we get the URL. Here is an example using curl::
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
219
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
220 curl -u demo:demo -s -X POST -H "Referer: https://.../demo/" \
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
221 -H "X-requested-with: rest" \
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
222 -H "Content-Type: application/json" \
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
223 --data '' \
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
224 https://.../demo/rest/data/issue/@poe
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
225
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
226 This will return a json payload like::
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
227
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
228 {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
229 "data": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
230 "expires": 1555266310.4457426,
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
231 "link": "https://.../demo/rest/data/issue/@poe/vizl713xHtIzANRW9jPb3bWXePRzmehdmSXzEta1"
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
232 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
233 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
234
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
235 The value of expires is a Unix timestamp in seconds. In this case it
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
236 has the default lifetime of 30 minutes after the current time. Using
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
237 the link more than 30 minutes into the future will cause a 400 error.
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
238
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
239 Within 30 minutes, the link can be used to post an issue with the same
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
240 payload that would normally be sent to:
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
241 ``https://.../demo/rest/data/issue``.
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
242
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
243 For example::
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
244
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
245 curl -u demo:demo -s -X POST \
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
246 -H "Referer: https://.../demo/" \
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
247 -H "X-requested-with: rest" \
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
248 -H "Content-Type: application/json" \
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
249 --data-binary '{ "title": "a problem" }' \
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
250 https://.../demo/rest/data/issue/@poe/vizl713xHtIzANRW9jPb3bWXePRzmehdmSXzEta1
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
251
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
252 returns::
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
253
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
254 {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
255 "data": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
256 "link": "https://.../demo/rest/data/issue/2280",
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
257 "id": "2280"
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
258 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
259 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
260
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
261 Once the @poe link is used and creates an issue, it becomes invalid
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
262 and can't be used again. Posting to it after the issue, or other
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
263 object, is created, results in a 400 error [#poe_retry]_.
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
264
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
265 Note that POE links are by restricted to the class that was used to
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
266 get the link. So you can only create an issue using the link returned
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
267 from ``rest/data/issue/@poe``. You can create a generic POE link by adding
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
268 the "generic" field to the post payload::
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
269
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
270 curl -u demo:demo -s -X POST -H "Referer: https://.../demo/" \
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
271 -H "X-requested-with: rest" \
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
272 --data 'lifetime=100&generic=1' \
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
273 https://.../demo/rest/data/issue/@poe
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
274
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
275 This will return a link under: ``https://.../demo/rest/data/issue/@poe``::
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
276
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
277 {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
278 "data": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
279 "expires": 1555268640.9606116,
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
280 "link":
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
281 "https://.../demo/rest/data/issue/@poe/slPrzmEq6Q9BTjvcKhfxMNZL4uHXjbHCidY1ludZ"
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
282 }
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
283 }
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
284
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
285 You could use the link and change 'issue' to 'user' and it would work
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
286 to create a user. Creating generic POE tokens is *not* recommended,
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
287 but is available if a use case requires it.
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
288
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
289 This example also changes the lifetime of the POE url. This link has
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
290 a lifetime of 15 minutes (900 seconds). Using it after 16 minutes will
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
291 result in a 400 error. A lifetime up to 1 hour can be specified.
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
292
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
293 POE url's are an optional mechanism. If:
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
294
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
295 * you do not expect your client to retry a failed post,
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
296 * a failed post is unlikely (e.g. you are running over a local lan),
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
297 * there is a human using the client and who can intervene if a post
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
298 fails
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
299
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
300 you can use the url ``https://.../demo/data/<class>``. However if you
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
301 are using this mechanism to automate creation of objects and will
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
302 automatically retry a post until it succeeds, please use the POE
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
303 mechanism.
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
304
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
305 .. [#poe_retry] At some future date, performing a POST to the POE link
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
306 soon after it has been used to create an object will
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
307 change. It will not return a 400 error. It will will trigger a
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
308 redirect to the url for the created object. After some period
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
309 of time (maybe a week) the POE link will be removed and return
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
310 a 400 error. This is meant to allow the client (a time limited
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
311 way) to retrieve the created resource when the response was
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
312 lost.
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
313
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
314 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
315 ======================
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
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 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
318 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
319 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
320 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
321
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 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
323 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
324 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
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 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
327 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
328
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
329 $('#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
330 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
331 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
332 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
333 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
334 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
335 $.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
336 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
337 + 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
338 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
339 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
340 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
341 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
342
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 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
344 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
345 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
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 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
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 {
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 "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
351 "@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
352 "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
353 {
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 "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
355 "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
356 "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
357 },
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 {
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 "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
360 "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
361 "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
362 },
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
363 ...
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
364
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
365 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
366 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
367 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
368 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
369 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
370 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
371 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
372
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
373 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
374
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
375 .../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
376
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
377 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
378 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
379
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
380 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
381 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
382 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
383 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
384
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
385 {
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
386 "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
387 "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
388 "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
389 '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
390 },
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
391
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
392 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
393
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
394 === 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
395 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
396 === 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
397 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
398 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
399
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
400 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
401 fields can be used for subsearch and sorting.
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
402
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
403
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
404 Programming the REST API
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
405 ------------------------
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
406
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
407 You can extend the rest api for a tracker. This describes how to add
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
408 new rest end points. At some point it will also describe the rest.py
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
409 structure and implementation.
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
410
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
411 Adding new rest endpoints
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
412 =========================
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
413
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
414 Add or edit the file interfaces.py at the root of the tracker
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
415 directory.
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
416
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
417 In that file add::
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
418
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
419 from roundup.rest import Routing, RestfulInstance, _data_decorator
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
420 from roundup.exceptions import Unauthorised
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
421
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
422 class RestfulInstance:
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
423
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
424 @Routing.route("/summary2")
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
425 @_data_decorator
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
426 def summary2(self, input):
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
427 result = { "hello": "world" }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
428 return 200, result
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
429
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
430 will make a new endpoint .../rest/summary2 that you can test with::
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
431
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
432 $ curl -X GET .../rest/summary2
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
433 {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
434 "data": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
435 "hello": "world"
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
436 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
437 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
438
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
439 Similarly appending this to interfaces.py after summary2::
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
440
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
441 # handle more endpoints
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
442 @Routing.route("/data/<:class_name>/@schema", 'GET')
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
443 def get_element_schema(self, class_name, input):
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
444 result = { "schema": {} }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
445 uid = self.db.getuid ()
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
446 if not self.db.security.hasPermission('View', uid, class_name) :
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
447 raise Unauthorised('Permission to view %s denied' % class_name)
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
448
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
449 class_obj = self.db.getclass(class_name)
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
450 props = class_obj.getprops(protected=False)
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
451 schema = result['schema']
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
452
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
453 for prop in props:
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
454 schema[prop] = { "type": repr(class_obj.properties[prop]) }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
455
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
456 return result
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
457
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
458 ..
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
459 the # comment in the example is needed to preserve indention under Class.
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
460
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
461 returns some data about the class::
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
462
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
463 $ curl -X GET .../rest/data/issue/@schema
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
464 {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
465 "schema": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
466 "keyword": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
467 "type": "<roundup.hyperdb.Multilink to \"keyword\">"
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
468 },
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
469 "title": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
470 "type": "<roundup.hyperdb.String>"
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
471 },
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
472 "files": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
473 "type": "<roundup.hyperdb.Multilink to \"file\">"
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
474 },
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
475 "status": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
476 "type": "<roundup.hyperdb.Link to \"status\">"
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
477 }, ...
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
478 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
479 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
480
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
481
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
482 Adding other endpoints (e.g. to allow an OPTIONS query against
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
483 ``/data/issue/@schema``) is left as an exercise for the reader.

Roundup Issue Tracker: http://roundup-tracker.org/