Mercurial > p > roundup > code

annotate doc/rest.txt @ 5676:e70885fe72a4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
issue2551026: template variable not defined even though it is. Fix issue where variables defined in TAL expression are not available in the scope of the definition. (Tom Ekberg (tekberg))
author John Rouillard <rouilj@ieee.org>
date Tue, 26 Mar 2019 17:31:28 -0400
parents 6dc4dba1c225
children 1fa59181ce58
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
1
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
2 ====================
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
3 REST API for Roundup
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
4 ====================
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
5
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
6 .. contents::
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
7 :local:
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
8
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
9 Introduction
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
10 ------------
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
11
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
12 After the last 1.6.0 Release, a REST-API developed in 2015 during a Google
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
13 Summer of Code (GSOC) by Chau Nguyen, supervised by Ezio Melotti was
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
14 integrated. The code was then updated by John Rouillard and Ralf
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
15 Schlatterbeck to fix some shortcomings and provide the necessary
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
16 functions for a single page web application, e.g. etag support among
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
17 others.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
18
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
19 Enabling the REST API
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
20 ---------------------
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
21
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
22 The REST API can be disabled in the ``[web]`` section of ``config.ini``
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
23 via the variable ``enable_rest`` which is ``yes`` by default.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
24
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
25 The REST api is reached via the ``/rest/`` endpoint of the tracker URL.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
26
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
27
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
28 Client API
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
29 ----------
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
30
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
31 The top-level REST url ``/rest/`` will display the current version of
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
32 the REST API (Version 1 as of this writing) and some links to relevant
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
33 endpoints of the API. In the following the ``/rest`` prefix is ommitted
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
34 from relative REST-API links for brevety.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
35
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
36 Summary
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
37 =======
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
38
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
39 A Summary page can be reached via ``/data/summary`` via the ``GET`` method.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
40 This is currently hard-coded for the standard tracker schema shipped
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
41 with roundup and will display a summary of open issues.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
42
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
43 Data
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
44 ====
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
45
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
46 All the links mentioned in the following support the http method ``GET``.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
47 Results of a ``GET`` request will always return the results as a
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
48 dictionary with the entry ``data`` referring to the returned data.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
49
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
50 The ``/data`` link will display a set of classes of the tracker. All
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
51 classes can be reached via ``/data/<classname>`` where ``<classname>``
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
52 is replace with the name of the class to query, e.g. ``/data/issue``.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
53 Individual items of a class (e.g. a single issue) can be queried by
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
54 giving the issue-id, e.g., ``/data/issue/42``. Individual properties of
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
55 an item can be queried by appending the property, e.g.,
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
56 ``/data/issue/42/title``.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
57
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
58 When performing the ``GET`` method on a class (e.g. ``/data/issue``), the
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
59 number of items is returned in ``@total_size``. Then a ``collection``
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
60 list follows which contains the id and link to the respective item.
5663
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
61 This endpoint supports pagination. With the attributes @page_size and
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
62 @page_index, pagination is controlled. The @page_size specifies how many
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
63 items are displayed at once. The @page_index (which defaults to 1 if not
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
64 given) specifies which page number of @page_size items is displayed. If
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
65 no @page_size is specified, all items are returned.
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
66 In addition this method supports searching. Search parameters are names
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
67 of properties of the given class, e.g., ``status`` for ``issue``. Links
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
68 and Multilinks can be specified numerically or symbolically, e.g.,
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
69 searching for issues in status ``closed`` can be achieved by searching
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
70 for ``status=closed`` or ``status=3`` (provided the ``closed`` status
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
71 has ID 3). Note that searching for strings (e.g. the issue title)
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
72 performs a case-insensitive substring search, so searching for
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
73 title=Something will find all issues with "Something" or "someThing",
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
74 etc. in the title. There is currently no way to perform an exact string
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
75 match.
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
76
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
77 When performing the ``GET`` method on an item (e.g. ``/data/issue/42``), a
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
78 ``link`` attribute contains the link to the item, ``id`` contains the
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
79 id, type contains the class name (e.g. ``issue`` in the example) and an
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
80 ``etag`` property can be used to detect modifications since the last
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
81 query. The individual properties of the item are returned in an
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
82 ``attributes`` dictionary. The properties returned depend on the
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
83 permissions of the account used for the query.
5663
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
84 Link and Multilink properties are displayed as a dictionary with a link
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
85 and an id property by default. This is controlled by the @verbose
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
86 attribute which is set to 1 by default. If set to 0, only the id is
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
87 shown for Link and Multilink attributes. If set to 2, the label property
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
88 (usually ``name`` e.g. for status) is also put into the dictionary.
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
89 Content properties of message and file object are by default also shown
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
90 as a dictionary with a sole link attribute. The link is the download
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
91 link for the file or message. If @verbose is >= 3, the content property
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
92 is shown in json as a (possibly very long) string. Currently the json
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
93 serializer cannot handle files not properly utf-8 encoded, so specifying
a884698173ea Document searching and @verbose attribute
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5660
diff changeset
94 @verbose=3 for files is currently discouraged.
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
95
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
96 A ``GET`` method on a property (e.g. ``/data/issue/42/title``) returns the
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
97 link, an ``@etag``, the type of the property (e.g. "<type str>") the id
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
98 of the item and the content of the property in ``data``.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
99
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
100 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
101 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
102 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
103 parameters as the GET method after successful creation.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
104
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
105 All endpoints support an ``OPTIONS`` method for determining which
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
106 methods are allowed on a given endpoint.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
107
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
108 The method ``PUT`` is allowed on individual items, e.g.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
109 ``/data/issue/42`` as well as properties, e.g.,
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
110 ``/data/issue/42/title``. On success it returns the same parameters as
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
111 the respective ``GET`` method. Note that for ``PUT`` an Etag has to be
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
112 supplied, either in the request header or as an @etag parameter.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
113
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
114 The method ``DELETE`` is allowed on items, e.g., ``/data/issue/42`` and
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
115 will retire (mark as deleted) the respective item. On success it will
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
116 only return a status code. It is also possible to call ``DELETE`` on a
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
117 property of an item, e.g., ``/data/issue/42/nosy`` to delete the nosy
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
118 list. The same effect can be achieved with a ``PUT`` request and an
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
119 empty new value.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
120
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
121 Finally the ``PATCH`` method can be applied to individual items, e.g.,
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
122 ``/data/issue/42`` and to properties, e.g., ``/data/issue/42/title``.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
123 This method gets an operator ``@op=<method>`` where ``<method`` is one
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
124 of ``add``, ``replace``, ``remove``, only for an item (not for a
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
125 property) an additional operator ``action`` is supported. If no operator
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
126 is specified, the default is ``replace``. The first three operators are
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
127 self explanatory. For an ``action`` operator an ``@action_name`` and
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
128 optional ``@action_argsXXX`` parameters have to be supplied. Currently
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
129 there are only two actions without parameters, namely ``retire`` and
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
130 ``restore``. The ``retire`` action on an item is the same as a
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
131 ``DELETE`` method, it retires the item. The ``restore`` action is the
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
132 inverse of ``retire``, the item is again visible.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
133 On success the returned value is the same as the respective ``GET``
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
134 method.
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
135
5674
6dc4dba1c225 REST: Use If-Match header for incoming requests
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5663
diff changeset
136 Note that the ``GET`` method on an item (e.g. ``/data/issue/43``)
6dc4dba1c225 REST: Use If-Match header for incoming requests
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5663
diff changeset
137 returns an ETag in the http header *and* the ``@etag`` value. When
6dc4dba1c225 REST: Use If-Match header for incoming requests
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5663
diff changeset
138 modifying the item via ``PUT`` or ``PATCH`` either a ``If-Match`` header
6dc4dba1c225 REST: Use If-Match header for incoming requests
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5663
diff changeset
139 or an ``@etag`` value in the form have to be provided.
6dc4dba1c225 REST: Use If-Match header for incoming requests
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5663
diff changeset
140
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
141 sample python client
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
142 ====================
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
143
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
144 The client uses the python ``requests`` library for easier interaction
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
145 with a REST API supporting JSON encoding::
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
146
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
147
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
148 >>> import requests
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
149 >>> u = 'http://user:password@tracker.example.com/demo/rest/data/'
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
150 >>> s = requests.session()
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
151 >>> r = s.get(u + 'issue/42/title')
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
152 >>> if r.status_code != 200:
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
153 ... print("Failed: %s: %s" % (r.status_code, r.reason))
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
154 ... exit(1)
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
155 >>> print (r.json() ['data']['data']
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
156 TEST Title
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
157 >>> r = s.post (u + 'issue', data = dict (title = 'TEST Issue'))
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
158 >>> if not 200 <= r.status_code <= 201:
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
159 ... print("Failed: %s: %s" % (r.status_code, r.reason))
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
160 ... exit(1)
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
161 >>> print(r.json())
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
162
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
163 Retire/Restore::
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
164 >>> r = s.delete (u + 'issue/42')
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
165 >>> print (r.json())
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
166 >>> r = s.get (u + 'issue/42')
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
167 >>> etag = r.headers['ETag']
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
168 >>> print("ETag: %s" % etag)
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
169 >>> etag = r.json()['data']['@etag']
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
170 >>> print("@etag: %s" % etag)
5674
6dc4dba1c225 REST: Use If-Match header for incoming requests
Ralf Schlatterbeck <rsc@runtux.com>
parents: 5663
diff changeset
171 >>> h = {'If-Match': etag}
5660
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
172 >>> d = {'@op:'action', '@action_name':'retire'}
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
173 >>> r = s.patch(u + 'issue/42', data = d, headers = h)
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
174 >>> print(r.json())
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
175 >>> d = {'@op:'action', '@action_name':'restore'}
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
176 >>> r = s.patch(u + 'issue/42', data = d, headers = h)
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
177 >>> print(r.json())
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
178
Roundup Issue Tracker: http://roundup-tracker.org/