Mercurial > p > roundup > code

comparison doc/rest.txt @ 7600:5a8a41a2e3c8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
docs: rewrite segments using ahref paragraph rewriter.
author John Rouillard <rouilj@ieee.org>
date Thu, 10 Aug 2023 09:50:45 -0400
parents 978285986b2c
children c5307dc0e8c6
comparison
equal deleted inserted replaced
7599:2c6acd503f00 7600:5a8a41a2e3c8
18 Introduction 18 Introduction
19 ============ 19 ============
20 20
21 After the last 1.6.0 Release, a REST-API developed in 2015 during a 21 After the last 1.6.0 Release, a REST-API developed in 2015 during a
22 Google Summer of Code (GSOC) by Chau Nguyen, supervised by Ezio 22 Google Summer of Code (GSOC) by Chau Nguyen, supervised by Ezio
23 Melotti was integrated. The code was updated by Ralf Schlatterbeck 23 Melotti was integrated. The code was updated by Ralf Schlatterbeck and
24 and John Rouillard to fix some shortcomings and provide the necessary 24 John Rouillard to address some limitations and incorporate essential
25 functions for a single page web application, e.g. etag support, 25 features for a single page web application, such as etag support,
26 pagination, field embedding among others. 26 pagination, and field embedding, among others.
27 27
28 Enabling the REST API 28 Enabling the REST API
29 ===================== 29 =====================
30 30
31 The REST API can be disabled in the ``[web]`` section of ``config.ini`` 31 The REST API can be disabled in the ``[web]`` section of ``config.ini``
79 79
80 Rate Limiting API Failed Logins 80 Rate Limiting API Failed Logins
81 ------------------------------- 81 -------------------------------
82 82
83 To make brute force password guessing harder, the REST API has an 83 To make brute force password guessing harder, the REST API has an
84 invalid login rate limiter. It rate limits the number of failed login 84 invalid login rate limiter. This feature restricts the number of
85 attempts with an invalid user or password. Valid login attempts are 85 failed login attempts made with an invalid user or
86 managed by the normal API rate limiter. The rate limiter is a GCRA 86 password. Successful login attempts are limited by the normal API rate
87 leaky bucket variant. All APIs (REST/XMLRPC) share the same rate 87 limiter. The rate limiter is a GCRA leaky bucket variant, which is
88 limiter. The rate limiter for the HTML/web interface is not shared by 88 shared by all API (REST/XMLRPC) endpoints. However it is important to
89 note that the rate limiter for the HTML/web interface is not shared by
89 the API failed login rate limiter. 90 the API failed login rate limiter.
90 91
91 It is configured by settings in config.ini. Setting 92 It is configured through the settings in config.ini. By setting the
92 ``api_failed_login_limit`` to a non-zero value enabled the limiter. 93 value of ``api_failed_login_limit`` to a non-zero value, the limiter
93 Setting it to 0 disables the limiter (not suggested). If a user fails 94 is enabled. Setting it to 0 will disables the limiter (although this
94 to log in more than ``api_failed_login_limit`` times in 95 is not recommended). If a user fails to log in more than
96 ``api_failed_login_limit`` times in
95 ``api_failed_login_interval_in_sec`` seconds, a 429 HTTP error will be 97 ``api_failed_login_interval_in_sec`` seconds, a 429 HTTP error will be
96 returned. The error also tell the user how long they must wait to try 98 returned. The error message also tells the user how long to wait
97 to log in again. 99 before trying to log in again.
98 100
99 When a 429 error is returned, the account is locked until enough time 101 When a 429 error is returned, the associated account will be
100 has passed 102 temporarily locked until sufficient time has elapsed to generate an
101 (``api_failed_login_interval_in_sec/api_failed_login_limit`` seconds) 103 additional login token. This time period is determined by the values
102 to make one additional login token available. Any attempt to log in 104 of the ``api_failed_login_interval_in_sec`` and ``api_failed_login_limit``
103 while it is locked will fail. This is true even if a the correct 105 parameters. Any login attempts made during this lockout period will be
104 password is supplied for a locked account. This means a brute force 106 unsuccessful, even if the correct password is provided. This
105 attempt can't try more than one password every 107 effectively prevents brute force attacks from attempting more than one
106 ``api_failed_login_interval_in_sec/api_failed_login_limit`` seconds on 108 password every
107 average. 109 ``api_failed_login_interval_in_sec/api_failed_login_limit`` seconds on average.
108 110
109 The default values allow up to 4 attempts to login before delaying the 111 The system's default settings permit a maximum of four login attempts,
110 user by 2.5 minutes (150 seconds). At this time there is no supported 112 after which the user will experience a delay of 2.5 minutes (150
111 method to reset the rate limiter. 113 seconds). Currently, there is no established procedure for resetting
114 the rate limiter.
112 115
113 Rate Limiting the API 116 Rate Limiting the API
114 --------------------- 117 ---------------------
115 118
116 This is a work in progress. This version of roundup includes Rate 119 Roundup includes Rate Limiting for the API, which is distinct from
117 Limiting for the API (which is different from rate limiting login 120 rate limiting login attempts on the web interface.
118 attempts on the web interface). 121
119 122 This feature can be enabled by setting the ``api_calls_per_interval``
120 It is enabled by setting the ``api_calls_per_interval`` and 123 and ``api_interval_in_sec`` configuration parameters in the ``[web]``
121 ``api_interval_in_sec`` configuration parameters in the ``[web]`` 124 section of the ``config.ini`` file. Details for these settings are
122 section of ``config.ini``. The settings are documented in the 125 documented in the same file.
123 config.ini file.
124 126
125 If ``api_calls_per_interval = 60`` and ``api_interval_in_sec = 60`` 127 If ``api_calls_per_interval = 60`` and ``api_interval_in_sec = 60``
126 the user can make 60 calls in a minute. They can use them all up in the 128 the user can make 60 calls in a minute. They can use them all up in the
127 first second and then get one call back every second. With 129 first second and then get one call back every second. With
128 ``api_calls_per_interval = 60`` and ``api_interval_in_sec = 3600`` (1 130 ``api_calls_per_interval = 60`` and ``api_interval_in_sec = 3600`` (1
133 ``api_calls_per_interval/api_interval_in_sec``. So you can have many 135 ``api_calls_per_interval/api_interval_in_sec``. So you can have many
134 values that permit one call per second on average: 1/1, 60/60, 136 values that permit one call per second on average: 1/1, 60/60,
135 3600/3600, but they all have a different maximum burst rates: 1/sec, 137 3600/3600, but they all have a different maximum burst rates: 1/sec,
136 60/sec and 3600/sec. 138 60/sec and 3600/sec.
137 139
138 A single page app may make 20 or 30 calls to populate the page (e.g. a 140 In practice, a single page app may require 20 or 30 API calls to
139 list of open issues). Then wait a few seconds for the user to select 141 populate the page with data, followed by a few seconds of waiting for
140 an issue. When displaying the issue, it needs another 20 or calls to 142 the user to select an issue. When displaying the issue, another 20 or
141 populate status dropdowns, pull the first 10 messages in the issue 143 more calls may be needed to populate status dropdowns, retrieve the
142 etc. Controlling the burst rate as well as the average rate is a 144 first 10 messages in the issue, and so on. Therefore, controlling both
143 tuning exercise left for the tracker admin. 145 the burst rate and the average rate is a tuning exercise that is left
144 146 to the tracker admin.
145 Also the rate limit is a little lossy. Under heavy load, it is 147
146 possible for it to miscount allowing more than burst count. Errors of 148 It is worth noting that the rate limit feature may be slightly lossy,
147 up to 10% have been seen on slower hardware. 149 meaning that under heavy load, it may miscount and allow more than the
150 burst count. On slower hardware, errors of up to 10% have been
151 observed. Using redis, PostgreSQL, or MySQL for storing ephemeral data
152 minimizes the loss.
148 153
149 Client API 154 Client API
150 ========== 155 ==========
151 156
152 The top-level REST url ``/rest/`` will display the current version of 157 The top-level REST url ``/rest/`` will display the current version of
Roundup Issue Tracker: http://roundup-tracker.org/