Mercurial > p > roundup > code

annotate doc/rest.txt @ 5663:a884698173ea

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Document searching and @verbose attribute
author Ralf Schlatterbeck <rsc@runtux.com>
date Fri, 22 Mar 2019 14:43:21 +0100
parents d8d2b7724292
children 6dc4dba1c225
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
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
136 sample python client
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
137 ====================
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
138
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
139 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
140 with a REST API supporting JSON encoding::
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
141
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 >>> import requests
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
144 >>> 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
145 >>> s = requests.session()
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
146 >>> r = s.get(u + 'issue/42/title')
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
147 >>> if r.status_code != 200:
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
148 ... print("Failed: %s: %s" % (r.status_code, r.reason))
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
149 ... exit(1)
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
150 >>> print (r.json() ['data']['data']
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
151 TEST Title
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
152 >>> 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
153 >>> if not 200 <= r.status_code <= 201:
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
154 ... print("Failed: %s: %s" % (r.status_code, r.reason))
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
155 ... exit(1)
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
156 >>> print(r.json())
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
157
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
158 Retire/Restore::
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
159 >>> r = s.delete (u + 'issue/42')
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
160 >>> print (r.json())
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
161 >>> r = s.get (u + 'issue/42')
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
162 >>> etag = r.headers['ETag']
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
163 >>> print("ETag: %s" % etag)
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
164 >>> etag = r.json()['data']['@etag']
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
165 >>> print("@etag: %s" % etag)
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
166 >>> h = dict(ETag = etag)
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
167 >>> d = {'@op:'action', '@action_name':'retire'}
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
168 >>> 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
169 >>> print(r.json())
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
170 >>> d = {'@op:'action', '@action_name':'restore'}
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
171 >>> 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
172 >>> print(r.json())
d8d2b7724292 First attempt at REST-API documentation
Ralf Schlatterbeck <rsc@runtux.com>
parents:
diff changeset
173
Roundup Issue Tracker: http://roundup-tracker.org/