update documentation

docs/_sources/installation.rst.txt

@@ -10,6 +10,7 @@ This application is written in Python (API) and Typescript (client):
     - `python-forecast.io <https://github.com/ZeevG/python-forecast.io>`_ to fetch weather data from `Dark Sky <https://darksky.net>`__ (former forecast.io)
     - `dramatiq <https://flask-dramatiq.readthedocs.io/en/latest/>`_ for task queue
     - `Authlib <https://docs.authlib.org/en/latest/>`_ for OAuth 2.0 Authorization support
+    - `Flask-Limiter <https://flask-limiter.readthedocs.io/en/stable>`_ for API rate limits
 - Client:
     - Vue3/Vuex
     - `Leaflet <https://leafletjs.com/>`__ to display map
@@ -21,13 +22,16 @@ This application is written in Python (API) and Typescript (client):
 Prerequisites
 ~~~~~~~~~~~~~
 
--  Python 3.7+
+- mandatory
--  PostgreSQL database (10+)
+    - Python 3.7+
--  SMTP provider and Redis for task queue (if email sending is enabled)
+    - PostgreSQL 10+
--  API key from `Dark Sky <https://darksky.net/dev>`__ (not mandatory)
+- optional
--  `Poetry <https://poetry.eustace.io>`__ (for installation from sources only)
+    - Redis for task queue (if email sending is enabled) and API rate limits
--  `Yarn <https://yarnpkg.com>`__ (for development only)
+    - SMTP provider (if email sending is enabled)
--  Docker and Docker Compose (for development or evaluation purposes)
+    - API key from `Dark Sky <https://darksky.net/dev>`__
+    - `Poetry <https://poetry.eustace.io>`__ (for installation from sources only)
+    - `Yarn <https://yarnpkg.com>`__ (for development only)
+    -  Docker and Docker Compose (for development or evaluation purposes)
 
 .. note::
     | The following steps describe an installation on Linux systems (tested
@@ -156,7 +160,7 @@ deployment method.
 
     .. versionadded:: 0.3.0
 
-    Redis instance used by **Dramatiq**.
+    Redis instance used by **Dramatiq** and **Flask-Limiter**.
 
     :default: local Redis instance (``redis://``)
 
@@ -168,6 +172,15 @@ deployment method.
     Number of processes used by **Dramatiq**.
 
 
+.. envvar:: API_RATE_LIMITS 🆕
+
+    .. versionadded:: 0.7.0
+
+    API rate limits, see `API rate limits <installation.html#api-rate-limits>`__.
+
+    :default: `300 per 5 minutes`
+
+
 .. envvar:: TILE_SERVER_URL
 
     .. versionadded:: 0.4.0
@@ -178,7 +191,7 @@ deployment method.
     :default: `https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png`
 
 
-.. envvar:: STATICMAP_SUBDOMAINS 🆕
+.. envvar:: STATICMAP_SUBDOMAINS
 
     .. versionadded:: 0.6.10
 
@@ -289,6 +302,42 @@ For instance, to set OSM France tile server, the expected values are:
 The subdomain will be chosen randomly.
 
 
+API rate limits 🆕
+^^^^^^^^^^^^^^^^^^
+.. versionadded:: 0.7.0
+
+| API rate limits are managed by `Flask-Limiter <https://flask-limiter.readthedocs.io/en/stable>`_, based on IP with fixed window strategy.
+| To enable rate limits, **Redis** must be available.
+
+.. note::
+    | If no Redis instance is available for rate limits, FitTrackee can still start.
+
+| All endpoints are subject to rate limits, except endpoints serving assets.
+| Limits can be modified by setting the environment variable ``API_RATE_LIMITS`` (see `Flask-Limiter documentation for notation <https://flask-limiter.readthedocs.io/en/stable/configuration.html#rate-limit-string-notation>`_).
+| Rate limits must be separated by a comma, for instance:
+
+.. code-block::
+
+    export API_RATE_LIMITS="200 per day, 50 per hour"
+
+**Flask-Limiter** provides a `Command Line Interface <https://flask-limiter.readthedocs.io/en/stable/cli.html>`_ for maintenance and diagnostic purposes.
+
+.. code-block:: bash
+
+    $ flask limiter
+    Usage: flask limiter [OPTIONS] COMMAND [ARGS]...
+
+      Flask-Limiter maintenance & utility commmands
+
+    Options:
+      --help  Show this message and exit.
+
+    Commands:
+      clear   Clear limits for a specific key
+      config  View the extension configuration
+      limits  Enumerate details about all routes with rate limits
+
+
 Installation
 ~~~~~~~~~~~~
 

docs/genindex.html

@@ -124,6 +124,8 @@
     environment variable
 
       <ul>
+        <li><a href="installation.html#envvar-API_RATE_LIMITS">API_RATE_LIMITS 🆕</a>
+</li>
         <li><a href="installation.html#envvar-APP_LOG">APP_LOG</a>
 </li>
         <li><a href="installation.html#envvar-APP_SECRET_KEY">APP_SECRET_KEY</a>
@@ -152,7 +154,7 @@
 </li>
         <li><a href="installation.html#envvar-SENDER_EMAIL">SENDER_EMAIL</a>
 </li>
-        <li><a href="installation.html#envvar-STATICMAP_SUBDOMAINS">STATICMAP_SUBDOMAINS 🆕</a>
+        <li><a href="installation.html#envvar-STATICMAP_SUBDOMAINS">STATICMAP_SUBDOMAINS</a>
 </li>
         <li><a href="installation.html#envvar-TILE_SERVER_URL">TILE_SERVER_URL</a>
 </li>

docs/installation.html

@@ -85,9 +85,10 @@
 <li><a class="reference internal" href="#environment-variables">Environment variables</a><ul>
 <li><a class="reference internal" href="#emails">Emails</a></li>
 <li><a class="reference internal" href="#map-tile-server">Map tile server</a></li>
+<li><a class="reference internal" href="#api-rate-limits">API rate limits 🆕</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#id1">Installation</a><ul>
+<li><a class="reference internal" href="#id2">Installation</a><ul>
 <li><a class="reference internal" href="#from-pypi">From PyPI</a></li>
 <li><a class="reference internal" href="#from-sources">From sources</a><ul>
 <li><a class="reference internal" href="#dev-environment">Dev environment</a></li>
@@ -97,9 +98,9 @@
 </ul>
 </li>
 <li><a class="reference internal" href="#upgrade">Upgrade</a><ul>
-<li><a class="reference internal" href="#id2">From PyPI</a></li>
+<li><a class="reference internal" href="#id3">From PyPI</a></li>
-<li><a class="reference internal" href="#id3">From sources</a><ul>
+<li><a class="reference internal" href="#id4">From sources</a><ul>
-<li><a class="reference internal" href="#id4">Dev environment</a></li>
+<li><a class="reference internal" href="#id5">Dev environment</a></li>
 <li><a class="reference internal" href="#prod-environment">Prod environment</a></li>
 </ul>
 </li>
@@ -107,7 +108,7 @@
 </li>
 <li><a class="reference internal" href="#deployment">Deployment</a></li>
 <li><a class="reference internal" href="#docker">Docker</a><ul>
-<li><a class="reference internal" href="#id5">Installation</a></li>
+<li><a class="reference internal" href="#id6">Installation</a></li>
 <li><a class="reference internal" href="#development">Development</a></li>
 </ul>
 </li>
@@ -172,6 +173,7 @@
 <li><p><a class="reference external" href="https://github.com/ZeevG/python-forecast.io">python-forecast.io</a> to fetch weather data from <a class="reference external" href="https://darksky.net">Dark Sky</a> (former forecast.io)</p></li>
 <li><p><a class="reference external" href="https://flask-dramatiq.readthedocs.io/en/latest/">dramatiq</a> for task queue</p></li>
 <li><p><a class="reference external" href="https://docs.authlib.org/en/latest/">Authlib</a> for OAuth 2.0 Authorization support</p></li>
+<li><p><a class="reference external" href="https://flask-limiter.readthedocs.io/en/stable">Flask-Limiter</a> for API rate limits</p></li>
 </ul>
 </dd>
 </dl>
@@ -193,14 +195,27 @@
 <section id="prerequisites">
 <h2>Prerequisites<a class="headerlink" href="#prerequisites" title="Permalink to this heading">¶</a></h2>
 <ul class="simple">
+<li><dl class="simple">
+<dt>mandatory</dt><dd><ul>
 <li><p>Python 3.7+</p></li>
-<li><p>PostgreSQL database (10+)</p></li>
+<li><p>PostgreSQL 10+</p></li>
-<li><p>SMTP provider and Redis for task queue (if email sending is enabled)</p></li>
+</ul>
-<li><p>API key from <a class="reference external" href="https://darksky.net/dev">Dark Sky</a> (not mandatory)</p></li>
+</dd>
+</dl>
+</li>
+<li><dl class="simple">
+<dt>optional</dt><dd><ul>
+<li><p>Redis for task queue (if email sending is enabled) and API rate limits</p></li>
+<li><p>SMTP provider (if email sending is enabled)</p></li>
+<li><p>API key from <a class="reference external" href="https://darksky.net/dev">Dark Sky</a></p></li>
 <li><p><a class="reference external" href="https://poetry.eustace.io">Poetry</a> (for installation from sources only)</p></li>
 <li><p><a class="reference external" href="https://yarnpkg.com">Yarn</a> (for development only)</p></li>
 <li><p>Docker and Docker Compose (for development or evaluation purposes)</p></li>
 </ul>
+</dd>
+</dl>
+</li>
+</ul>
 <div class="admonition note">
 <p class="admonition-title">Note</p>
 <div class="line-block">
@@ -392,7 +407,7 @@ see <a class="reference external" href="https://docs.sqlalchemy.org/en/13/core/p
 <dd><div class="versionadded">
 <p><span class="versionmodified added">New in version 0.3.0.</span></p>
 </div>
-<p>Redis instance used by <strong>Dramatiq</strong>.</p>
+<p>Redis instance used by <strong>Dramatiq</strong> and <strong>Flask-Limiter</strong>.</p>
 <dl class="field-list simple">
 <dt class="field-odd">Default<span class="colon">:</span></dt>
 <dd class="field-odd"><p>local Redis instance (<code class="docutils literal notranslate"><span class="pre">redis://</span></code>)</p>
@@ -409,6 +424,20 @@ see <a class="reference external" href="https://docs.sqlalchemy.org/en/13/core/p
 <p>Number of processes used by <strong>Dramatiq</strong>.</p>
 </dd></dl>
 
+<dl class="std envvar">
+<dt class="sig sig-object std" id="envvar-API_RATE_LIMITS">
+<span class="sig-name descname"><span class="pre">API_RATE_LIMITS</span> <span class="pre">🆕</span></span><a class="headerlink" href="#envvar-API_RATE_LIMITS" title="Permalink to this definition">¶</a></dt>
+<dd><div class="versionadded">
+<p><span class="versionmodified added">New in version 0.7.0.</span></p>
+</div>
+<p>API rate limits, see <a class="reference external" href="installation.html#api-rate-limits">API rate limits</a>.</p>
+<dl class="field-list simple">
+<dt class="field-odd">Default<span class="colon">:</span></dt>
+<dd class="field-odd"><p><cite>300 per 5 minutes</cite></p>
+</dd>
+</dl>
+</dd></dl>
+
 <dl class="std envvar">
 <dt class="sig sig-object std" id="envvar-TILE_SERVER_URL">
 <span class="sig-name descname"><span class="pre">TILE_SERVER_URL</span></span><a class="headerlink" href="#envvar-TILE_SERVER_URL" title="Permalink to this definition">¶</a></dt>
@@ -428,7 +457,7 @@ see <a class="reference external" href="https://docs.sqlalchemy.org/en/13/core/p
 
 <dl class="std envvar">
 <dt class="sig sig-object std" id="envvar-STATICMAP_SUBDOMAINS">
-<span class="sig-name descname"><span class="pre">STATICMAP_SUBDOMAINS</span> <span class="pre">🆕</span></span><a class="headerlink" href="#envvar-STATICMAP_SUBDOMAINS" title="Permalink to this definition">¶</a></dt>
+<span class="sig-name descname"><span class="pre">STATICMAP_SUBDOMAINS</span></span><a class="headerlink" href="#envvar-STATICMAP_SUBDOMAINS" title="Permalink to this definition">¶</a></dt>
 <dd><div class="versionadded">
 <p><span class="versionmodified added">New in version 0.6.10.</span></p>
 </div>
@@ -572,9 +601,48 @@ The tile server can be changed by updating <code class="docutils literal notrans
 </ul>
 <p>The subdomain will be chosen randomly.</p>
 </section>
+<section id="api-rate-limits">
+<h3>API rate limits 🆕<a class="headerlink" href="#api-rate-limits" title="Permalink to this heading">¶</a></h3>
+<div class="versionadded">
+<p><span class="versionmodified added">New in version 0.7.0.</span></p>
+</div>
+<div class="line-block">
+<div class="line">API rate limits are managed by <a class="reference external" href="https://flask-limiter.readthedocs.io/en/stable">Flask-Limiter</a>, based on IP with fixed window strategy.</div>
+<div class="line">To enable rate limits, <strong>Redis</strong> must be available.</div>
+</div>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<div class="line-block">
+<div class="line">If no Redis instance is available for rate limits, FitTrackee can still start.</div>
+</div>
+</div>
+<div class="line-block">
+<div class="line">All endpoints are subject to rate limits, except endpoints serving assets.</div>
+<div class="line">Limits can be modified by setting the environment variable <code class="docutils literal notranslate"><span class="pre">API_RATE_LIMITS</span></code> (see <a class="reference external" href="https://flask-limiter.readthedocs.io/en/stable/configuration.html#rate-limit-string-notation">Flask-Limiter documentation for notation</a>).</div>
+<div class="line">Rate limits must be separated by a comma, for instance:</div>
+</div>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">export</span> <span class="n">API_RATE_LIMITS</span><span class="o">=</span><span class="s2">&quot;200 per day, 50 per hour&quot;</span>
+</pre></div>
+</div>
+<p><strong>Flask-Limiter</strong> provides a <a class="reference external" href="https://flask-limiter.readthedocs.io/en/stable/cli.html">Command Line Interface</a> for maintenance and diagnostic purposes.</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ flask limiter
+Usage: flask limiter <span class="o">[</span>OPTIONS<span class="o">]</span> COMMAND <span class="o">[</span>ARGS<span class="o">]</span>...
+
+  Flask-Limiter maintenance <span class="p">&amp;</span> utility commmands
+
+Options:
+  --help  Show this message and exit.
+
+Commands:
+  clear   Clear limits <span class="k">for</span> a specific key
+  config  View the extension configuration
+  limits  Enumerate details about all routes with rate limits
+</pre></div>
+</div>
 </section>
-<section id="id1">
+</section>
-<h2>Installation<a class="headerlink" href="#id1" title="Permalink to this heading">¶</a></h2>
+<section id="id2">
+<h2>Installation<a class="headerlink" href="#id2" title="Permalink to this heading">¶</a></h2>
 <div class="admonition warning">
 <p class="admonition-title">Warning</p>
 <div class="line-block">
@@ -776,8 +844,8 @@ database credentials</strong>):</p></li>
 <div class="line">- upload directory (see <a class="reference external" href="installation.html#environment-variables">Environment variables</a>)</div>
 </div>
 </div>
-<section id="id2">
+<section id="id3">
-<h3>From PyPI<a class="headerlink" href="#id2" title="Permalink to this heading">¶</a></h3>
+<h3>From PyPI<a class="headerlink" href="#id3" title="Permalink to this heading">¶</a></h3>
 <ul class="simple">
 <li><p>Stop the application and activate the virtualenv</p></li>
 <li><p>Upgrade with pip</p></li>
@@ -802,10 +870,10 @@ $ <span class="nb">source</span> .env
 <li><p>Restart the application and task queue workers (if email sending is enabled).</p></li>
 </ul>
 </section>
-<section id="id3">
-<h3>From sources<a class="headerlink" href="#id3" title="Permalink to this heading">¶</a></h3>
 <section id="id4">
-<h4>Dev environment<a class="headerlink" href="#id4" title="Permalink to this heading">¶</a></h4>
+<h3>From sources<a class="headerlink" href="#id4" title="Permalink to this heading">¶</a></h3>
+<section id="id5">
+<h4>Dev environment<a class="headerlink" href="#id5" title="Permalink to this heading">¶</a></h4>
 <ul class="simple">
 <li><p>Stop the application and pull the repository:</p></li>
 </ul>
@@ -996,8 +1064,8 @@ server {
 </section>
 <section id="docker">
 <h2>Docker<a class="headerlink" href="#docker" title="Permalink to this heading">¶</a></h2>
-<section id="id5">
+<section id="id6">
-<h3>Installation<a class="headerlink" href="#id5" title="Permalink to this heading">¶</a></h3>
+<h3>Installation<a class="headerlink" href="#id6" title="Permalink to this heading">¶</a></h3>
 <div class="versionadded">
 <p><span class="versionmodified added">New in version 0.4.4.</span></p>
 </div>