wip

kcech · Nov 5, 2020 · d301b27 · d301b27
1 parent 94665fd
commit d301b27
Show file tree

Hide file tree

Showing 5 changed files with 105 additions and 6 deletions.
diff --git a/docs/_static/images/api_docs/rl_entity_190.png b/docs/_static/images/api_docs/rl_entity_190.png
diff --git a/docs/api_docs/general_model.rst b/docs/api_docs/general_model.rst
@@ -159,6 +159,9 @@ response **HTTP status codes.**
 | 403                   | Forbidden             | Not authorized for    |
 |                       |                       | the requested action  |
 +-----------------------+-----------------------+-----------------------+
+| 429                   | Too Many Requests     | Global quota or       |
+|                       |                       | entity quota exceed   |
++-----------------------+-----------------------+-----------------------+
 | 5xx                   | Server Error          | Error processing the  |
 |                       |                       | request               |
 +-----------------------+-----------------------+-----------------------+

diff --git a/docs/api_docs/rate_limiting.rst b/docs/api_docs/rate_limiting.rst
@@ -1,2 +1,97 @@
 Rate Limiting
-=============
+=============
+
+Since v1.9, Sentilo offers rate limiting features for the REST API.
+
+Rest limiting prevents the Sentilo instance from request flooding and also protects
+subscribed external systems by limiting outbound requests.
+
+Setting global limits
+---------------------
+
+You can set global incoming quota `api.global_rate_limit.quota` in file
+sentilo-platform/sentilo-platform-server/src/main/resources/properties/config.properties.
+If left unset or set to 0, Sentilo won't apply no global limit.
+
+Also, global body length can be set using `api.body.max_length` variable.
+
+::
+
+   # number of requests per hour
+   api.global_rate_limit.quota=100
+
+   # Maximum body length in bytes
+   api.body.max_length=4096
+
+
+If global rate limiting is set, every response of the API contains following headers:
+
++--------------------------------------+-----------------------------------------------------+
+|                Header                |                     Description                     |
++======================================+=====================================================+
+| X-RateLimit-Global-Inbound-Limit     | Value of the api.global_rate_limit.quota property   |
++--------------------------------------+-----------------------------------------------------+
+| X-RateLimit-Global-Inbound-Remaining | Number of remaining requests until the current      |
+|                                      | limit per hour is exceed                            |
++--------------------------------------+-----------------------------------------------------+
+| X-RateLimit-Global-Inbound-Reset     | If the API limit is exceeded, this value indicates  |
+|                                      | the number of minutes until the server will accept  |
+|                                      | requests again. Otherwise is 0.                     |
++--------------------------------------+-----------------------------------------------------+
+
+In case the input quota is exceed, the server will reject the request and return a HTTP error code 429.
+In case the maximum payload size is exceed, the server responses with HTTP error code 400.
+
+
+
+
+Limit requests by entity
+------------------------
+
+A provider or an application can have particular limits, which can be configured in catalogue:
+
+|rl_entity_190.png|
+
+If input quota for a entity is different from 0, every response of the API contains following headers:
+
++--------------------------------------+-----------------------------------------------------+
+|                Header                |                     Description                     |
++======================================+=====================================================+
+| X-RateLimit-Inbound-Limit            | Value of the input quota                            |
++--------------------------------------+-----------------------------------------------------+
+| X-RateLimit-Inbound-Remaining        | Number of remaining requests until the current      |
+|                                      | limit per hour is exceed                            |
++--------------------------------------+-----------------------------------------------------+
+| X-RateLimit-Inbound-Reset            | If the entity quota is exceeded, this value         |
+|                                      | indicates the number of minutes until entity will   |
+|                                      | be permitted again. Otherwise is 0.                 |
++--------------------------------------+-----------------------------------------------------+
+
+If output quota for a entity is different from 0, every subscription request that Sentilo sends to the
+subscription endpoint will contain following headers:
+
++--------------------------------------+-----------------------------------------------------+
+|                Header                |                     Description                     |
++======================================+=====================================================+
+| X-RateLimit-Outbound-Limit           | Value of the output quota                           |
++--------------------------------------+-----------------------------------------------------+
+| X-RateLimit-Outbound-Remaining       | Number of remaining requests until the current      |
+|                                      | limit per hour is exceed                            |
++--------------------------------------+-----------------------------------------------------+
+| X-RateLimit-Outbound-Reset           | This value indicates the number of minutes until    |
+|                                      | the counter of remaining outgoing requests of the   |
+|                                      | entity will be reset. Otherwise is 0.               |
++--------------------------------------+-----------------------------------------------------+
+
+For example, consider the following case:
+
+-  X-RateLimit-Outbound-Limit: 5
+-  X-RateLimit-Outbound-Remaining: 1
+-  X-RateLimit-Outbound-Reset: 58
+
+We can see that this entity that is subscribed to Sentilo data has a output quota set to  5 notifications/hour,
+that it can still receive 1 more notification and that the current window is still valid during next 58 minutes.
+
+
+
+.. |rl_entity_190.png| image:: _static/images/api_docs/rl_entity_190.png
diff --git a/docs/api_docs/security.rst b/docs/api_docs/security.rst
@@ -19,8 +19,12 @@ actions:
 -  Check that it can do the requested action on the resource indicated.
 -  Register the performed action.
 
-When necessary, the platform will check the integrity and
-confidentiality of communications is ensured using **HTTPS** protocol.
+.. note::
+
+   Sentilo itself does not provide a mechanism to SSL/TLS http protocol (inbound https requests).
+   That's because we don't need to duplicate the work of others - Sentilo is typically deployed
+   behind a reverse proxy or an API manager, which already handle the encrypted connections very well.
+
 
 Authentication
 ~~~~~~~~~~~~~~

diff --git a/docs/api_docs/services/data/retrieve_provider_sensor_data.rst b/docs/api_docs/services/data/retrieve_provider_sensor_data.rst
@@ -24,9 +24,6 @@ indicate the maximum number of observations to be recovered.
 +----------------+----------------------------------------------------+
 
 
-**Because the number of sensors from a supplier can be very high, and
-therefore the amount of information returned can be very large, be
-careful using this operations due to performance reasons.**
 
 Parameteres
 -----------