Mercurial > p > roundup > code

annotate doc/rest.txt @ 5726:e199d0ae4a25

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
issue2551033: prevent reverse engineering hidden data by using etags as an oracle to identify when the right data has been guessed. Identified by Joseph Myers who also suggested remediation methods. Implemented John Rouillard.
author John Rouillard <rouilj@ieee.org>
date Thu, 23 May 2019 18:56:57 -0400
parents 59a3bbd3603a
children 07d8bbf6ee5f
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:
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
8 :depth: 3
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
9
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
10 Introduction
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
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
13 After the last 1.6.0 Release, a REST-API developed in 2015 during a
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
14 Google Summer of Code (GSOC) by Chau Nguyen, supervised by Ezio
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
15 Melotti was integrated. The code was updated by John Rouillard and
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
16 Ralf Schlatterbeck to fix some shortcomings and provide the necessary
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
17 functions for a single page web application, e.g. etag support,
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
18 pagination, field embedding among others.
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
19
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
20 Enabling the REST API
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
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
23 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
24 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
25
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
26 The REST api is reached via the ``/rest/`` endpoint of the tracker
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
27 URL. Partial URLs paths below (not starting with https) will have
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
28 /rest removed for brevity.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
29
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
30 Preventing CSRF Attacks
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
31 =======================
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
32
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
33 Clients should set the header X-REQUESTED-WITH to any value and the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
34 tracker's config.ini should have ``csrf_enforce_header_x-requested-with
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
35 = yes`` or ``required``.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
36
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
37 Rate Limiting the API
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
38 =====================
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
39
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
40 This is a work in progress. Check the release notes to see if your
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
41 version of roundup includes Rate Limiting for the API (which is
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
42 different from rate limiting login attempts on the web interface).
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
43
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
44 This is enabled by setting the ``api_calls_per_interval`` and
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
45 ``api_interval_in_sec`` configuration parameters in the ``[web]``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
46 section of ``config.ini``. The settings are documented in the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
47 config.ini file.
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
48
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
49 If ``api_calls_per_interval = 60`` and ``api_interval_in_sec = 60``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
50 the user can make 60 calls in a minute. They can use them all up in the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
51 first second and then get one call back every second. With
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
52 ``api_calls_per_interval = 60`` and ``api_interval_in_sec = 3600`` (1
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
53 hour) they can use all 60 calls in the first second and they get one
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
54 additional call every 10 seconds. ``api_calls_per_interval`` is the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
55 burst rate that you are willing to allow within `api_interval_in_sec``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
56 seconds. The average rate of use is the ratio of
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
57 ``api_calls_per_interval/api_interval_in_sec``. So you can have many
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
58 values that permit one call per second on average: 1/1, 60/60,
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
59 3600/3600, but they all have a different maximum burst rates: 1/sec,
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
60 60/sec and 3600/sec.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
61
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
62 A single page app may make 20 or 30 calls to populate the page (e.g. a
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
63 list of open issues). Then wait a few seconds for the user to select
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
64 an issue. When displaying the issue, it needs another 20 or calls to
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
65 populate status dropdowns, pull the first 10 messages in the issue
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
66 etc. Controlling the burst rate as well as the average rate is a
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
67 tuning exercise left for the tracker admin.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
68
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
69 Also the rate limit is a little lossy. Under heavy load, it is
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
70 possible for it to miscount allowing more than burst count. Errors of
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
71 up to 10% have been seen on slower hardware.
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
72
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
73 Client API
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
74 ----------
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
75
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
76 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
77 the REST API (Version 1 as of this writing) and some links to relevant
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
78 endpoints of the API. In the following the ``/rest`` prefix is omitted
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
79 from relative REST-API links for brevity.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
80
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
81 Headers
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
82 =======
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
83
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
84 If rate limiting is enabled there are 3 "standard" headers:
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
85
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
86 **X-RateLimit-Limit**: Calls allowed per period.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
87
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
88 **X-RateLimit-Remaining**: Calls available to be completed in this window.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
89
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
90 **X-RateLimit-Reset**: window ends in this many seconds. (Note,
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
91 not an epoch timestamp). After this time, all
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
92 X-RateLimit-Limit calls are available again.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
93
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
94 and one helpful header to report the period that is missing
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
95 from other lists of rate limit headers:
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
96
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
97 **X-RateLimit-Limit-Period**: Defines period in seconds for X-RateLimit-Limit.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
98
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
99 Also if the user has exceeded the rate limit, this header is added:
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
100
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
101 **Retry-After**: The number of second to wait until 1 api call will succeed.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
102
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
103
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
104 General Guidelines
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
105 ==================
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
106
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
107 Performing a ``GET`` on an item or property of an item will rethrn an
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
108 ETag header or an @etag property. This needs to be submitted with
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
109 ``DELETE``, ``PUT`` and ``PATCH`` operations on the item using an
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
110 ``If-Match`` header or an ``"@etag`` property in the data payload if
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
111 the method supports a payload.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
112
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
113 The exact details of returned data is determined by the value of the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
114 ``@verbose`` query parameter. The various supported values and their
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
115 effects are described in the following sections.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
116
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
117 The default return format is JSON. If you add the ``dicttoxml.py``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
118 module you can request XML formatted data using the header ``Accept:
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
119 application/xml`` in your request. Both output formats are similar in
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
120 structure.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
121
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
122 All output is wrapped in an envelope called ``data``.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
123
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
124 When using collection endpoints (think list of issues, users ...), the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
125 ``data`` envelope contains metadata (e.g. total number of items) as
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
126 well as a ``collections`` list of objects::
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
127
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
128 { "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
129 "meta data field1": "value",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
130 "meta data field2": "value",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
131 "collecton": [
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
132 { "link": "url to item",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
133 "id": "internal identifier for item" },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
134 { "link": "url to second item",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
135 "id": "id item 2" },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
136 ... ]
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
137 "@links": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
138 "relation": [
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
139 { "rel": "relation/subrelation",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
140 "uri": "uri to use to implement relation" },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
141 ...
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
142 ],
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
143 "relation2": [ {...} ], ...
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
144 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
145 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
146 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
147
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
148 available meta data is described in the documention for the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
149 collections endpoint.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
150
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
151 The ``link`` fields implement HATEOS by supplying a url for the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
152 resource represented by that object. The "link" parameter with the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
153 value of a url is a special case of the @links parameter.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
154
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
155 In the @links object, each relationship is a list of full link json
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
156 objects. These include rel (relationship) and uri properties. In the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
157 future this may be extended to include other data like content-type.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
158 However including a full @links object for every item includes a lot
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
159 of overhead since in most cases only the self relationship needs to be
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
160 represented.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
161
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
162 Because every object, link and multilink ends up getting a url, the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
163 shorter 'link' representation is used for this special case. The
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
164 ``link`` property expresses the ``self`` relationship and its value is
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
165 the uri property of the full link object. In collections, properties
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
166 from each item can be embedded in the returned data (see ``@fields``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
167 below). This can not be done if the property is called link as that
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
168 conflicts with the self url.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
169
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
170 When using an item endpoint (think an individual issue), metadata is
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
171 included in the ``data`` envelope. Inside of the envelope, the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
172 ``attributes`` object contains the data for the field/properties of
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
173 the issue. Example::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
174
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
175 { "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
176 "meta data field1": "value",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
177 "type": "type of item, issue, user ..."
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
178 "link": "link to retreive item",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
179 "attributes": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
180 "title": "title of issue",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
181 "nosy": [
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
182 { "link": "url for user4",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
183 "id": "4" }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
184 ],
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
185
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
186 ... }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
187 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
188 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
189
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
190 Using a property endpoint (e.g. title or nosy list for an issue) the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
191 ``data`` wrapper has a ``data`` subfield that represents the value of
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
192 the property. This ``data`` subfield may be a simple string (all types
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
193 except mutlilink) or a list of strings (multilink
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
194 properties). Example::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
195
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
196 { "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
197 "type": "description of class",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
198 "@etag": "\"f15e6942f00a41960de45f9413684591\"",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
199 "link": "link to retreive property",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
200 "id": "id for object with this property",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
201 "data": "value of property"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
202 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
203 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
204
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
205
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
206 Special Endpoints
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
207 =================
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
208
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
209 There are a few special endpoints that provide some additional data.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
210 Tracker admiinstrators can add new endpoints. See
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
211 "Programming the REST API"_ below.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
212
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
213 /summary
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
214 ^^^^^^^^
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
215
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
216 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
217 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
218 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
219
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
220 /data
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
221 ^^^^^
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
222
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
223 This is the primary entry point for data from the tracker.
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
224
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
225 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
226 classes can be reached via ``/data/<classname>`` where ``<classname>``
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
227 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
228 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
229 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
230 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
231 ``/data/issue/42/title``.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
232
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
233
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
234 All the links mentioned in the following support the http method ``GET``.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
235 Results of a ``GET`` request will always return the results as a
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
236 dictionary with the entry ``data`` referring to the returned data.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
237
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
238 Details are in the sections below.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
239
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
240 /data/\ *class* Collection
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
241 ==========================
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
242
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
243 When performing the ``GET`` method on a class (e.g. ``/data/issue``),
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
244 the ``data`` object includes the number of items available in
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
245 ``@total_size``. A a ``collection`` list follows which contains the id
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
246 and link to the respective item. For example a get on
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
247 https://.../rest/data/issue returns::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
248
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
249 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
250 "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
251 "collection": [
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
252 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
253 "id": "1",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
254 "link": "https://.../rest/data/issue/1"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
255 },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
256 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
257 "id": "100",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
258 "link": "https://.../rest/data/issue/100"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
259 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
260 ...
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
261 ],
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
262 "@total_size": 171
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
263 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
264 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
265
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
266 Collection endpoints support a number of features as seen in the next
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
267 sections.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
268
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
269 Searching
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
270 ^^^^^^^^^
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
271
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
272 Searching is done by adding roundup field names and values as query
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
273 parameters. Using: https://.../rest/data/issue you can search using:
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
274
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
275 .. list-table:: Query Parameters Examples
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
276 :header-rows: 1
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
277 :widths: 20 20 80
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
278
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
279 * - Query parameter
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
280 - Field type
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
281 - Explanation
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
282 * - ``title=foo``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
283 - String
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
284 - perform a substring search and find any issue with the word foo
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
285 in the title.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
286 * - ``status=2``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
287 - Link
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
288 - find any issue whose status link is set to the id 2.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
289 * - ``status=open``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
290 - Link
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
291 - find any issue where the name of the status is open.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
292 Note this is not a string match so using nosy=ope will fail.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
293 * - ``nosy=1``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
294 - MultiLink
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
295 - find any issue where the multilink nosy includes the id 1.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
296 * - ``nosy=admin``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
297 - MultiLink
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
298 - find any issue where the multilink nosy includes the user admin.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
299 Note this is not a string match so using nosy=admi will fail.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
300 * - ``booleanfield=1`` - also values: true, TRUE, yes, YES etc. Other
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
301 values match false.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
302 - Boolean
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
303 - find an issue with the boolean field set to true.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
304
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
305 As seen above, Links and Multilinks can be specified numerically or
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
306 symbolically, e.g., searching for issues in status ``closed`` can be
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
307 achieved by searching for ``status=closed`` or ``status=3`` (provided
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
308 the ``closed`` status has ID 3). Note that even though the symbolic
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
309 name is a string, in this case it is also a key value. As a result it
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
310 only does an exact match.
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
311
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
312 Searching for strings (e.g. the issue title, or a keyword name)
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
313 performs a case-insensitive substring search, so searching for
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
314 title=Something will find all issues with "Something" or "someThing",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
315 etc. in the title. There is currently no way to perform an exact
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
316 string match.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
317
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
318 To make this clear, searching
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
319 ``https://.../rest/data/issue?keyword=foo`` will not work unless there
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
320 is a keyword with a name field of ``foo`` which is the key field of
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
321 the keyword. However searching the text property ``name`` using
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
322 ``https://.../rest/data/keyword?name=foo`` (note searching keyword
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
323 class not issue class) will return matches for ``foo``, ``foobar``,
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
324 ``foo taz`` etc.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
325
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
326 In all cases the field ``@total_size`` is reported which is the total
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
327 number of items available if you were to retreive all of them.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
328
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
329 Other data types: Date, Interval Integer, Number need examples and may
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
330 need work to allow range searches. Full text search (e.g. over the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
331 body of msgs) is a work in progress.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
332
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
333 Pagination
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
334 ^^^^^^^^^^
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
335
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
336 Collection endpoints support pagination. This is controlled by query
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
337 parameters ``@page_size`` and ``@page_index`` (Note the use of the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
338 leading `@` to make the parameters distinguishable from field names.)
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
339
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
340 .. list-table:: Query Parameters Examples
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
341 :header-rows: 1
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
342 :widths: 20 80
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
343
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
344 * - Query parameter
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
345 - Explanation
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
346 * - ``@page_size``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
347 - specifies how many items are displayed at once. If no
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
348 ``@page_size`` is specified, all matching items are returned.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
349 * - ``@page_index``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
350 - (which defaults to 1 if not given) specifies which page number
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
351 of ``@page_size`` items is displayed.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
352
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
353 Also when pagenation is enabled the returned data include pagenation
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
354 links along side the collection data. This looks like::
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
355
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
356 { "data":
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
357 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
358 "collection": { ... },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
359 "@total_size": 222,
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
360 "@links": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
361 "self": [
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
362 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
363 "uri":
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
364 "https://.../rest/data/issue?@page_index=1&@fields=status&@page_size=5",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
365 "rel": "self"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
366 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
367 ],
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
368 "next": [
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
369 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
370 "uri":
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
371 "https://.../rest/data/issue?@page_index=2&@fields=status&@page_size=5",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
372 "rel": "next"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
373 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
374 ]
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
375 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
376 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
377 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
378
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
379 The ``@links`` parameter is a dictionary indexed by
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
380 relationships. Each relationship is a list of one or more full link
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
381 json objects. Above we have link relations to move to the next
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
382 page. If we weren't at the first page, there would be a ``prev``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
383 relation to move to the previous page. Also we have a self relation
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
384 (which is missing the @page_index, hence we are at page 1) that can be
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
385 used to get the same page again.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
386
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
387
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
388 Field embedding and verbose output
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
389 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
390
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
391 In collections, you can specify what fields should be embedded in the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
392 returned data. There are some shortcuts provided using the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
393 ``@verbose`` parameter. All the examples in this section are for a GET
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
394 operation on ``https://.../rest/data/issue``.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
395
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
396 .. list-table:: Query Parameters Examples
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
397 :header-rows: 1
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
398 :widths: 20 80
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
399
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
400 * - Query parameter
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
401 - Explanation
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
402 * - ``@verbose=0``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
403 - each item in the collection has its "id" property displayed
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
404 and a link with the URL to retreive the item.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
405 * - ``@verbose=1``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
406 - for collections this output is the same as ``@verbose=0``. This
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
407 is the default.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
408 * - ``@verbose=2``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
409 - each item in the collection includes the "label" property in
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
410 addition to "id" property and a link for the item.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
411 This is useful as documented below in "Searches and selection"_.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
412 * - ``@verbose=3``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
413 - will display the content property of messages and files. Note
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
414 warnings about this below. Using this for collections is
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
415 discouraged as it is slow and produces a lot of data.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
416 * - ``@fields=status,title``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
417 - will return the ``status`` and ``title`` fields for the issue displayed
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
418 according to the @verbose parameter
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
419
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
420 In addition collections support the ``@fields`` parameter which is a
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
421 colon or comma separated list of fields to embed in the response. For
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
422 example ``https://.../rest/data/issue?@verbose=2`` is the same as:
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
423 ``https://.../rest/data/issue?@fields=title`` since the label property
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
424 for an issue is its title. You can use both ``@verbose`` and
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
425 ``@fields`` to get additional info. For example
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
426 ``https://.../rest/data/issue?@verbose=2&@fields=status`` returns::
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
427
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
428 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
429 "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
430 "collection": [
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
431 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
432 "link":
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
433 "https://.../rest/data/issue/1",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
434 "title": "Welcome to the tracker START HERE",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
435 "id": "1",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
436 "status": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
437 "link":
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
438 "https://.../rest/data/status/1",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
439 "id": "1",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
440 "name": "new"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
441 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
442 },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
443 ...
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
444 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
445
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
446 the format of the status field (included because of
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
447 ``@fields=status``) includes the label for the status. This is due to
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
448 inclusion of ``@verbose=2``. Without verbose you would see::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
449
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
450 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
451 "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
452 "collection": [
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
453 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
454 "link":
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
455 "https://.../rest/data/issue/1",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
456 "id": "1",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
457 "status": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
458 "link":
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
459 "https://.../rest/data/status/1",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
460 "id": "1"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
461 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
462 },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
463 ...
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
464 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
465
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
466 Note that the ``link`` field that is returned doesn't exist in the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
467 database. It is a construct of the rest interface. This means that you
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
468 can not set ``@fields=link`` and get the link property included in the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
469 output.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
470
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
471 Also using ``@fields=@etag`` will not work to retreive the etag for
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
472 items in the collection.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
473
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
474 See the `Searches and selection`_ section for the use cases supported
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
475 by these features.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
476
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
477
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
478 Other query params
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
479 ^^^^^^^^^^^^^^^^^^
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
480
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
481 This table lists other supported parameters:
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
482
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
483 .. list-table:: Query Parameters Examples
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
484 :header-rows: 1
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
485 :widths: 20 80
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
486
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
487 * - Query parameter
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
488 - Explanation
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
489 * - ``@pretty=false``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
490 - by default json data is pretty printed to make it readable to
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
491 humans. This eases testing and with compression enabled the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
492 extra whitespace doesn't bloat the returned payload excessively.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
493 You can disable pretty printing by using this query parameter.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
494 Note the default is true, so @pretty=true is not supported at
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
495 this time.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
496
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
497 Using the POST method
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
498 ^^^^^^^^^^^^^^^^^^^^^
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
499
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
500 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
501 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
502 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
503 parameters as the GET method after successful creation.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
504
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
505 If you perform a get on an item with ``@verbose=0``, it is in the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
506 correct form to use as a the payload of a post.
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
507
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
508
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
509 Safely Re-sending POST
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
510 ^^^^^^^^^^^^^^^^^^^^^^
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
511
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
512 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
513 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
514 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
515 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
516
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
517 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
518 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
519 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
520
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
521 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
522 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
523
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
524 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
525
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
526 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
527 -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
528 -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
529 --data '' \
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
530 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
531
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
532 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
533
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
534 {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
535 "data": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
536 "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
537 "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
538 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
539 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
540
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
541 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
542 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
543 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
544
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
545 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
546 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
547 ``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
548
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
549 For example::
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
550
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
551 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
552 -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
553 -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
554 -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
555 --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
556 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
557
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
558 returns::
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
559
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
560 {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
561 "data": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
562 "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
563 "id": "2280"
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
564 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
565 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
566
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
567 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
568 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
569 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
570
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
571 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
572 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
573 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
574 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
575
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
576 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
577 -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
578 --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
579 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
580
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
581 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
582
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
583 {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
584 "data": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
585 "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
586 "link":
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
587 "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
588 }
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
589 }
5688
1b9ef04b9528 Add docs on how to add new rest endpoints.
John Rouillard <rouilj@ieee.org>
parents: 5678
diff changeset
590
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
591 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
592 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
593 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
594
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
595 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
596 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
597 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
598
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
599 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
600
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
601 * 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
602 * 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
603 * 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
604 fails
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
605
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
606 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
607 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
608 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
609 mechanism.
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
610
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
611 .. [#poe_retry] As a future enhancement, performing a POST to the POE
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
612 link soon after it has been used to create an object will
5710
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
613 change. It will not return a 400 error. It will will trigger a
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
614 301 redirect to the url for the created object. After some
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
615 period of time (maybe a week) the POE link will be removed and
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
616 return a 400 error. This is meant to allow the client (a time
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
617 limited way) to retrieve the created resource if the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
618 response was lost.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
619
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
620 Other Supported Methods for Collections
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
621 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
622
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
623 Supports the ``OPTIONS`` method for determining which methods are
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
624 allowed on a given endpoint.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
625
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
626 Does not support PUT, DELETE or PATCH.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
627
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
628 /data/\ *class*/\ *id* item
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
629 ===========================
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
630
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
631 When performing the ``GET`` method on an item
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
632 (e.g. ``/data/issue/42``), a ``link`` attribute contains the link to
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
633 the item, ``id`` contains the id, ``type`` contains the class name
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
634 (e.g. ``issue`` in the example) and an ``etag`` property can be used
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
635 to detect modifications since the last query.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
636
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
637 Individual properties of the item are returned in an ``attributes``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
638 dictionary. The properties returned depend on the permissions of the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
639 account used for the query.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
640
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
641 By default all (visible to the current user) attributes/properties are
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
642 returned. You can limit this by using the ``@fields`` query parameter
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
643 similar to how it is used in collections. This way you can only return
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
644 the fields you are interested in reducing network load as well as
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
645 memory and parsing time on the client side.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
646
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
647 Link and Multilink properties are displayed as a dictionary with a
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
648 ``link`` and an ``id`` property by default. This is controlled by the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
649 ``@verbose`` attribute which is set to 1 by default. If set to 0, only
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
650 the id is shown for Link and Multilink attributes. In this form, the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
651 data can be modified and sent back using ``PUT`` to change the item.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
652 If set to 2, the label property (usually ``name`` e.g. for status) is
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
653 also put into the dictionary. Content properties of message and file
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
654 object are by default also shown as a dictionary with a sole link
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
655 attribute. The link is the download link for the file or message. If
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
656 @verbose is >= 3, the content property is shown in json as a (possibly
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
657 very long) string. Currently the json serializer cannot handle files
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
658 not properly utf-8 encoded, so specifying @verbose=3 for files is
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
659 currently discouraged.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
660
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
661 An example of returned values::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
662
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
663 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
664 "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
665 "type": "issue",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
666 "@etag": "\"f15e6942f00a41960de45f9413684591\"",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
667 "link": "https://.../rest/data/issue/23",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
668 "attributes": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
669 "keyword": [],
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
670 "messages": [
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
671 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
672 "link": "https://.../rest/data/msg/375",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
673 "id": "375"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
674 },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
675 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
676 "link": "https://.../rest/data/msg/376",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
677 "id": "376"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
678 },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
679 ...
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
680 ],
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
681 "files": [],
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
682 "status": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
683 "link": "https://.../rest/data/status/2",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
684 "id": "2"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
685 },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
686 "title": "This is a title title",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
687 "superseder": [],
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
688 "nosy": [
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
689 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
690 "link": "https://.../rest/data/user/4",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
691 "id": "4"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
692 },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
693 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
694 "link": "https://.../rest/data/user/5",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
695 "id": "5"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
696 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
697 ],
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
698 "assignedto": null,
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
699 },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
700 "id": "23"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
701 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
702 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
703
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
704 Retrieve item using key value
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
705 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
706
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
707 If the class has a key attribute, e.g. the 'status' class in the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
708 classic tracker, it can be used to retried the item.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
709
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
710 You can get an individual status by specifying the key-attribute value
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
711 e.g. ``/data/status/name=closed``. Note that ``name`` in this example
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
712 must be the key-attribute of the class. A short-form (which might not
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
713 be supported in future version of the API) is to specify only the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
714 value, e.g. ``/data/status/closed``. This short-form only works when
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
715 you're sure that the key of the class is not numeric. E.G. if the name
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
716 was "7", /data/status/7 would return the status with id 7 not the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
717 status with name "7". To get the status with name 7, you must use
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
718 the long form /data/status/name=7
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
719
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
720 The long-form (with ``=``) is different from a query-parameter like
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
721 ``/data/status?name=closed`` which would find all stati (statuses)
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
722 that have ``closed`` as a substring.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
724
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
725 Other Supported Methods for Items
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
726 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
727
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
728 The method ``PUT`` is allowed on individual items, e.g.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
729 ``/data/issue/42`` On success it returns the same parameters as the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
730 respective ``GET`` method. Note that for ``PUT`` an Etag has to be
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
731 supplied, either in the request header or as an @etag parameter. An
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
732 example::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
733
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
734 curl -u admin:admin -X PUT \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
735 --header 'Referer: https://example.com/demo/' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
736 --header 'X-Requested-With: rest' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
737 --header "Content-Type: application/json" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
738 --header "Accept: application/json" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
739 --header 'If-Match: "dd41f02d6f8b4c34b439fc712b522fb3"' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
740 --data '{ "nosy": [ "1", "5" ] }' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
741 "https://example.com/demo/rest/data/issue/23"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
742
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
743 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
744 "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
745 "attribute": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
746 "nosy": [
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
747 "1",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
748 "5"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
749 ]
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
750 },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
751 "type": "issue",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
752 "link":
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
753 "https://example.com/demo/rest/data/issue/23",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
754 "id": "23"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
755 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
756 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
757
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
758 If the above command is repeated with the data attribute::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
759
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
760 --data '{ "nosy": [ "1", "5" ], "title": "This is now my title" }'
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
761
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
762 this is returned::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
763
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
764 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
765 "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
766 "attribute": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
767 "title": "This is now my title"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
768 },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
769 "type": "issue",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
770 "link":
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
771 "https://rouilj.dynamic-dns.net/demo/rest/data/issue/23",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
772 "id": "23"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
773 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
774 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
775
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
776 Note that nosy is not in the attributes returned. It is the same as
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
777 before, so no change has happened and it is not reported.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
778 Changing both nosy and title::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
779
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
780 curl -u admin:admin -X PUT \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
781 --header 'Referer: https://.../' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
782 --header 'X-Requested-With: rest' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
783 --header "Content-Type: application/json" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
784 --header "Accept: application/json" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
785 --header 'If-Match: "8209add59a79713d64f4d1a072aef740"' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
786 --data '{ "nosy": [ "4", "5" ], "title": "This is now my new title" }' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
787 "https://rouilj.dynamic-dns.net/demo/rest/data/issue/23"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
788
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
789 which returns both title and nosy attributes::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
790
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
791 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
792 "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
793 "attribute": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
794 "title": "This is now my new title",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
795 "nosy": [
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
796 "4",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
797 "5"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
798 ]
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
799 },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
800 "type": "issue",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
801 "link":
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
802 "https://rouilj.dynamic-dns.net/demo/rest/data/issue/23",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
803 "id": "23"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
804 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
805 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
806
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
807 Note that mixing url query parameters with payload submission doesn't
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
808 work. So using::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
809
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
810 https://.../rest/data/issue/23?@pretty=false
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
811
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
812 doesn't have the desired effect. However it can be put in the data
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
813 payload:
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
814
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
815 curl -u admin:admin ...
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
816 --data '{ "nosy": [ "4", "5" ], "title": "...", "@pretty": "false" }'
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
817
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
818 produces::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
819
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
820 {"data": {"attribute": {}, "type": "issue",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
821 "link": "https://...", "id": "23"}}
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
822
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
823 the lines are wrapped for display purposes, in real life it's one long
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
824 line.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
825
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
826 The method ``DELETE`` is allowed on items, e.g., ``/data/issue/42``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
827 and will retire (mark as deleted) the respective item. On success it
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
828 will only return a status code. The item is still available if
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
829 accessed directly by it's item url. The item will not show up in
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
830 searches where it would have been matched if not retired.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
831
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
832 Finally the ``PATCH`` method can be applied to individual items, e.g.,
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
833 ``/data/issue/42``. This method gets an operator ``@op=<method>``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
834 where ``<method>`` is one of ``add``, ``replace``, ``remove``. For
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
835 items, an additional operator ``action`` is supported. If no operator
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
836 is specified, the default is ``replace``. The first three operators
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
837 are self explanatory. For an ``action`` operator an ``@action_name``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
838 and optional ``@action_argsXXX`` parameters have to be
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
839 supplied. Currently there are only two actions, neither has args,
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
840 namely ``retire`` and ``restore``. The ``retire`` action on an item is
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
841 the same as a ``DELETE`` method, it retires the item. The ``restore``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
842 action is the inverse of ``retire``, the item is again visible. On
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
843 success the returned value is the same as the respective ``GET``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
844 method. An example to add a user to the nosy list of an item is:
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
845
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
846 curl -u admin:admin -p -X PATCH \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
847 --header "Content-Type: application/x-www-form-urlencoded" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
848 --header "Accept: application/json" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
849 --header 'If-Match: "c6e2d81019acff1da7a2da45f93939bd"' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
850 --data-urlencode '@op=add' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
851 --data 'nosy=3' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
852 "https://.../rest/data/issue/23"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
853
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
854 which returns::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
855
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
856 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
857 "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
858 "attribute": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
859 "nosy": [
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
860 "3",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
861 "4"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
862 ]
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
863 },
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
864 "type": "issue",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
865 "link": "https://.../rest/data/issue/23",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
866 "id": "23"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
867 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
868 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
869
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
870 Note that the changed values are returned so you can update
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
871 internal state in your app with the new data.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
872
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
873 The ``GET`` method on an item (e.g. ``/data/issue/43``) returns an
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
874 ETag in the http header *and* the ``@etag`` value in the json
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
875 payload. When modifying a property via ``PUT`` or ``PATCH`` or
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
876 ``DELETE`` the etag value for the item must be supplied using an
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
877 ``If-Match`` header. If you are using ``PUT`` or ``PATCH`` an
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
878 ``@etag`` value can be supplied in the payload in place of the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
879 ``If-Match`` header.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
880
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
881 /data/\ *class*/\ *id*/\ *property* field
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
882 =========================================
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
883
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
884 A ``GET`` method on a property (e.g. ``/data/issue/42/title``) returns the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
885 link, an ``@etag``, the type of the property (e.g. "<type str>") the id
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
886 of the item and the content of the property in ``data``.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
887
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
888 For example::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
889
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
890 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
891 "data": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
892 "link": "https://.../rest/data/issue/22/title",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
893 "data": "I need Broken PC",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
894 "type": "<class 'str'>",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
895 "id": "22",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
896 "@etag": "\"370510512b2d8fc3f98aac3d762cc7b1\""
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
897 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
898 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
899
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
900
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
901 All endpoints support an ``OPTIONS`` method for determining which
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
902 methods are allowed on a given endpoint.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
903
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
904 Other Supported Methods for fields
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
905 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
906
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
907 The method ``PUT`` is allowed on a property e.g.,
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
908 ``/data/issue/42/title``. On success it returns the same parameters as
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
909 the respective ``GET`` method. Note that for ``PUT`` an Etag has to be
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
910 supplied, either in the request header or as an @etag parameter.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
911 Example using multipart/form-data rather than json::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
912
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
913 curl -vs -u provisional:provisional -X PUT \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
914 --header "Accept: application/json" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
915 --data "data=Provisional" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
916 --header "If-Match: 079eba599152f3eed00567e23258fecf" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
917 --data-urlencode "@etag=079eba599152f3eed00567e23258fecf" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
918 "https://.../rest/data/user/5/realname"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
919
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
920 This example updates a leadtime field that is declared as an interval
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
921 type::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
922
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
923 curl -vs -u demo:demo -X PUT \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
924 --header "Accept: application/json" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
925 --header 'Content-Type: application/json' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
926 --header "Referer: https://.../" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
927 --header "x-requested-with: rest" \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
928 --header 'If-Match: "e2e6cc43c3475a4a3d9e5343617c11c3"' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
929 --data '{"leadtime": "2d" }' \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
930 "https://.../rest/data/issue/10"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
931
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
932 It is also possible to call ``DELETE`` on a
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
933 property of an item, e.g., ``/data/issue/42/nosy`` to delete the nosy
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
934 list. The same effect can be achieved with a ``PUT`` request and an
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
935 empty new value. This may fail if the property is required.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
936
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
937 The ``PATCH`` method can be applied to properties, e.g.,
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
938 ``/data/issue/42/title``. This method gets an operator
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
939 ``@op=<method>`` where ``<method>`` is one of ``add``, ``replace``,
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
940 ``remove``. If no operator is specified, the default is ``replace``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
941 which is the same as performing a PUT on the field url. ``add`` and
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
942 ``remove`` allow ading and removing values from MultiLink
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
943 properties. This is easier than having to rewrite the entire value for
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
944 the field using the ``replace`` operator or doing a PUT to the field.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
945 On success the returned value is the same as the respective ``GET``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
946 method.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
947
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
948 The ``GET`` method on an item (e.g. ``/data/issue/43``) returns an
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
949 ETag in the http header *and* the ``@etag`` value in the json
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
950 payload. When modifying a property via ``PUT`` or ``PATCH`` or
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
951 ``DELETE`` the etag value for the item must be supplied using an
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
952 ``If-Match`` header. If you are using ``PUT`` or ``PATCH`` an
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
953 ``@etag`` value can be supplied in the payload in place of the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
954 ``If-Match`` header.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
955
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
956 Tunneling Methods via POST
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
957 ==========================
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
958
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
959 If you are working through a proxy and unable to use http method like
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
960 PUT, PATCH or DELETE you can use POST to perform the action. To tunnel
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
961 an action throught POST, send the ``X-HTTP-METHOD-OVERRIDE`` header
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
962 with a value of DELETE or other capitalized HTTP verb. The body of the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
963 POST should be what you would send if you were using the method
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
964 without tunneling.
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
965
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
966 Examples and Use Cases
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
967 ----------------------
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
968
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
969 sample python client
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
970 ====================
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
971
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
972 The client uses the python ``requests`` library for easier interaction
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
973 with a REST API supporting JSON encoding::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
974
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
975
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
976 >>> import requests
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
977 >>> u = 'http://user:password@tracker.example.com/demo/rest/data/'
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
978 >>> s = requests.session()
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
979 >>> r = s.get(u + 'issue/42/title')
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
980 >>> if r.status_code != 200:
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
981 ... print("Failed: %s: %s" % (r.status_code, r.reason))
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
982 ... exit(1)
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
983 >>> print (r.json() ['data']['data']
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
984 TEST Title
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
985 >>> h = {'X-Requested-With': 'rest', 'Referer': 'http://tracker.example.com/demo/'}
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
986 >>> r = s.post (u + 'issue', data = dict (title = 'TEST Issue'), headers=h)
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
987 >>> if not 200 <= r.status_code <= 201:
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
988 ... print("Failed: %s: %s" % (r.status_code, r.reason))
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
989 ... exit(1)
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
990 >>> print(r.json())
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
991
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
992 Retire/Restore::
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
993 >>> r = s.delete (u + 'issue/42')
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
994 >>> print (r.json())
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
995 >>> r = s.get (u + 'issue/42')
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
996 >>> etag = r.headers['ETag']
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
997 >>> print("ETag: %s" % etag)
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
998 >>> etag = r.json()['data']['@etag']
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
999 >>> print("@etag: %s" % etag)
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1000 >>> h = {'If-Match': etag,
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1001 ... 'X-Requested-With': 'rest',
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1002 ... 'Referer': 'http://tracker.example.com/demo/'}
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1003 >>> d = {'@op:'action', '@action_name':'retire'}
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1004 >>> r = s.patch(u + 'issue/42', data = d, headers = h)
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1005 >>> print(r.json())
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1006 >>> d = {'@op:'action', '@action_name':'restore'}
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1007 >>> r = s.patch(u + 'issue/42', data = d, headers = h)
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1008 >>> print(r.json())
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1009
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1010 Note the addition of headers for: x-requested-with and referer. This
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1011 allows the request to pass the CSRF protection mechanism. You may need
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1012 to add an Origin header if this check is enabled in your tracker's
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1013 config.ini (look for csrf_enforce_header_origin).
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1014
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
1015
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
1016 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
1017 ======================
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1018
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1019 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
1020 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
1021 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
1022 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
1023
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1024 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
1025 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
1026 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
1027
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1028 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
1029 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
1030
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
1031 $('#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
1032 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
1033 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
1034 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
1035 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
1036 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
1037 $.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
1038 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
1039 + 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
1040 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
1041 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
1042 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
1043 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
1044
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1045 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
1046 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
1047 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
1048
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
1049 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
1050
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1051 {
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1052 "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
1053 "@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
1054 "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
1055 {
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1056 "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
1057 "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
1058 "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
1059 },
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1060 {
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1061 "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
1062 "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
1063 "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
1064 },
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
1065 ...
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
1066
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1067 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
1068 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
1069 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
1070 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
1071 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
1072 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
1073 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
1074
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
1075 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
1076
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1077 .../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
1078
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1079 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
1080 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
1081
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1082 A get on a collection endpoint can include other properties. Why do we
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1083 want this? Selectize.js can set up option groups (optgroups) in the
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1084 select pulldown. So by including status in the returned data using
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1085 a url like ``https://.../rest/data/issue?@verbose=2&@fields=status``
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1086 we get::
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
1087
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1088 {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1089 "link": "https://.../rest/data/issue/1001",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1090 "title": "Request for Broken PC",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1091 "id": "1001",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1092 "status": {
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1093 "link": "https://.../rest/data/status/6",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1094 "id": "6",
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1095 "name": "resolved"
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1096 }
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1097 }
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
1098
5695
3e1b66c4e1e2 Update docs. Correct errors reported by setup.py build_docs. Add rest
John Rouillard <rouilj@ieee.org>
parents: 5688
diff changeset
1099 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
1100
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1101 === 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
1102 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
1103 === 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
1104 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
1105 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
1106
1fa59181ce58 Add support for @verbose=2 to a GET on a collection object. Using this
John Rouillard <rouilj@ieee.org>
parents: 5674
diff changeset
1107 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
1108 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
1109
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1110
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1111 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
1112 ------------------------
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1113
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1114 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
1115 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
1116 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
1117
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1118 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
1119 =========================
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1120
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1121 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
1122 directory.
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1123
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1124 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
1125
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1126 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
1127 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
1128
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1129 class RestfulInstance:
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1130
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1131 @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
1132 @_data_decorator
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1133 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
1134 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
1135 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
1136
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1137 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
1138
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1139 $ 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
1140 {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1141 "data": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1142 "hello": "world"
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1143 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1144 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1145
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1146 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
1147
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1148 # 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
1149 @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
1150 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
1151 result = { "schema": {} }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1152 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
1153 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
1154 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
1155
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1156 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
1157 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
1158 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
1159
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1160 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
1161 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
1162
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1163 return result
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1164
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1165 ..
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1166 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
1167
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1168 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
1169
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1170 $ 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
1171 {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1172 "schema": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1173 "keyword": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1174 "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
1175 },
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1176 "title": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1177 "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
1178 },
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1179 "files": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1180 "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
1181 },
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1182 "status": {
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1183 "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
1184 }, ...
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1185 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1186 }
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1187
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1188
0b79bfcb3312 Add support for making an idempotent POST. This allows retrying a POST
John Rouillard <rouilj@ieee.org>
parents: 5698
diff changeset
1189 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
1190 ``/data/issue/@schema``) is left as an exercise for the reader.
5723
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1191
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1192
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1193 Test Examples
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1194 =============
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1195
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1196 Rate limit tests:
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1197
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1198 seq 1 300 | xargs -P 20 -n 1 curl --head -si \
59a3bbd3603a Expanded documentation. More examples, added sections based on each
John Rouillard <rouilj@ieee.org>
parents: 5710
diff changeset
1199 https://.../rest/data/status/new \# | grep Remaining
Roundup Issue Tracker: http://roundup-tracker.org/