feat(docs): document rate limits

api/api/settings.py

@@ -103,7 +103,7 @@ REST_FRAMEWORK = {
         'desecapi.throttling.ScopedRatesThrottle',
         'rest_framework.throttling.UserRateThrottle',
     ],
-    'DEFAULT_THROTTLE_RATES': {
+    'DEFAULT_THROTTLE_RATES': {  # When changing rate limits, make sure to keep docs/rate-limits.rst consistent
         # ScopedRatesThrottle
         'account_management_active': ['3/min'],  # things with side effect, e.g. sending mail or zone creation on signup
         'account_management_passive': ['10/min'],  # things like GET'ing v/* or auth/* URLs, or creating/deleting tokens

docs/dns/domains.rst

@@ -5,8 +5,10 @@ Domain Management
 
 Domain management is done through the ``/api/v1/domains/`` endpoint.  The
 following sections describe how to create, list, modify, and delete domains
-using JSON objects.  The structure of the JSON objects is detailed in the next
-section.
+using JSON objects.
+
+All operations are subject to rate limiting.  For details, see
+:ref:`rate-limits`.
 
 
 .. _`domain object`:

docs/dns/rrsets.rst

@@ -25,6 +25,9 @@ that don't exist or you don't own, the API responds with a ``404 Not Found``
 status code.  For a quick overview of the available endpoints, methods, and
 operations, see :ref:`endpoint-reference`.
 
+All operations are subject to rate limiting.  For details, see
+:ref:`rate-limits`.
+
 
 .. _`RRset object`:
 

docs/dyndns/update-api.rst

@@ -100,3 +100,6 @@ Update Response
 If successful, the server will return a response with status ``200 OK`` and
 ``good`` as the body (as per the dyndns2 protocol specification). For error
 status codes, see above.
+
+dynDNS updates are subject to rate limiting.  For details, see
+:ref:`rate-limits`.

docs/index.rst

@@ -52,6 +52,7 @@ of the `curl` call, like this::
    :caption: API Summary
 
    endpoint-reference
+   rate-limits
    lifecycle
 
 

docs/rate-limits.rst

@@ -0,0 +1,36 @@
+.. _rate-limits:
+
+Rate Limits
+-----------
+
+The API implements rate limits to prevent brute force attacks on passwords, to
+ensure that the system load remains manageable, to avoid update rejections due
+to concurrent DNS updates on the same domain etc.
+
+Rate limits apply per account.  The following table summarizes the rate limits
+pertaining to various parts of the API.  When several rates are given, all are
+enforced at the same time.  For throttled requests, the server will respond
+with ``429 Too Many Requests``.
+
+
++--------------------------------+----------+-------------------------------------------------------------------------------------------+
+| Rate limit name                | Rate     | Affected operations                                                                       |
++================================+==========+===========================================================================================+
+| ``account_management_active``  | 3/min    | Account activities with external effects (e.g. sending email)                             |
++--------------------------------+----------+-------------------------------------------------------------------------------------------+
+| ``account_management_passive`` | 10/min   | Account activities with internal effects (e.g. viewing account details, creating a token) |
++--------------------------------+----------+-------------------------------------------------------------------------------------------+
+| ``dyndns``                     | 1/min    | dynDNS updates                                                                            |
++--------------------------------+----------+-------------------------------------------------------------------------------------------+
+| ``dns_api_read``               | 10/s     | DNS read operations (e.g. fetching an RRset)                                              |
+|                                |          |                                                                                           |
+|                                | 50/min   |                                                                                           |
++--------------------------------+----------+-------------------------------------------------------------------------------------------+
+| ``dns_api_write``              | 6/s      | DNS write operations (e.g. create a domain, change an RRset)                              |
+|                                |          |                                                                                           |
+|                                | 50/min   |                                                                                           |
+|                                |          |                                                                                           |
+|                                | 200/h    |                                                                                           |
++--------------------------------+----------+-------------------------------------------------------------------------------------------+
+| ``user``                       | 1000/day | Any activity of a) authenticated users, b) unauthenticated users (by IP)                  |
++--------------------------------+----------+-------------------------------------------------------------------------------------------+