cartodb4/dataservices-api
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add new docs folder structure

Browse Source
This commit is contained in:
csubira
2018-02-22 17:25:12 +01:00
parent c14fb057d3
commit ef68ad4dcb
9 changed files with 1254 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

197
docs/support/02-rate-limits.md Normal file
View File

@@ -0,0 +1,197 @@
## Rate limits
Services can be rate-limited. (currently only gecoding is limited)
The rate limits configuration can be established at server, organization or user levels, the latter having precedence over the earlier.
The default configuration (a null or empty configuration) doesn't impose any limits.
The configuration consist of a JSON object with two attributes:
* `period`: the rate-limiting period, in seconds.
* `limit`: the maximum number of request in the established period.
If a service request exceeds the configured rate limits
(i.e. if more than `limit` calls are performe in a fixed interval of
duration `period` seconds) the call will fail with an "Rate limit exceeded" error.
### Server-side interface
There's a server-side SQL interface to query or change the configuration.
#### cdb_dataservices_server.cdb_service_get_rate_limit(username, orgname, service)
This function returns the rate limit configuration for a given user and service.
##### Returns
The result is a JSON object with the configuration (`period` and `limit` attributes as explained above).
#### cdb_dataservices_server.cdb_service_set_user_rate_limit(username, orgname, service, rate_limit)
This function sets the rate limit configuration for the user. This overrides any other configuration.
The configuration is provided as a JSON literal. To remove the user-level configuration `NULL` should be passed as the `rate_limit`.
##### Returns
This functions doesn't return any value.
#### cdb_dataservices_server.cdb_service_set_org_rate_limit(username, orgname, service, rate_limit)
This function sets the rate limit configuration for the organization.
This overrides server level configuration and is overriden by user configuration if present.
The configuration is provided as a JSON literal. To remove the organization-level configuration `NULL` should be passed as the `rate_limit`.
##### Returns
This functions doesn't return any value.
#### cdb_dataservices_server.cdb_service_set_server_rate_limit(username, orgname, service, rate_limit)
This function sets the default rate limit configuration for all users accesing the dataservices server. This is overriden by organization of user configuration.
The configuration is provided as a JSON literal. To remove the organization-level configuration `NULL` should be passed as the `rate_limit`.
##### Returns
This functions doesn't return any value.
### Client-side interface
For convenience there's also a client-side interface (in the client dataservices-api extension), consisting
of public functions to get the current configuration and privileged functions to change it.
#### Public functions
These functions are accesible to non-privileged roles, and should only be executed
using the role corresponding to a CARTO user, since that will determine the
user and organization to which the rate limits configuration applies.
#### cdb_dataservices_client.cdb_service_get_rate_limit(service)
This function returns the rate limit configuration in effect for the specified service
and the user corresponding to the role which makes the calls. The effective configuration
may come from any of the configuration levels (server/organization/user); only the
existing configuration with most precedence is returned.
##### Returns
The result is a JSON object with the configuration (`period` and `limit` attributes as explained above).
##### Example:
```
SELECT cdb_dataservices_client.cdb_service_get_rate_limit('geocoder');
cdb_service_get_rate_limit
---------------------------------
{"limit": 1000, "period": 86400}
(1 row)
```
#### Privileged (superuser) functions
Thes functions are not accessible by regular user roles, and the user and organization names must be provided as parameters.
#### cdb_dataservices_client.cdb_service_set_user_rate_limit(username, orgname, service, rate_limit)
This function sets the rate limit configuration for the user. This overrides any other configuration.
The configuration is provided as a JSON literal. To remove the user-level configuration `NULL` should be passed as the `rate_limit`.
##### Returns
This functions doesn't return any value.
##### Example
This will configure the geocoder service rate limit for user `myusername`, a non-organization user.
The limit will be set at 1000 requests per day. Since the user doesn't belong to any organization,
`NULL` will be passed to the organization argument; otherwise the name of the user's organization should
be provided.
Note that the name of the geocoding services is `geocoder` and not `geocoding`.
```
SELECT cdb_dataservices_client.cdb_service_set_user_rate_limit(
'myusername',
NULL,
'geocoder',
'{"limit":1000,"period":86400}'
);
cdb_service_set_user_rate_limit
---------------------------------
(1 row)
```
#### cdb_dataservices_client.cdb_service_set_org_rate_limit(username, orgname, service, rate_limit)
This function sets the rate limit configuration for the organization.
This overrides server level configuration and is overriden by user configuration if present.
The configuration is provided as a JSON literal. To remove the organization-level configuration `NULL` should be passed as the `rate_limit`.
##### Returns
This functions doesn't return any value.
##### Example
This will configure the geocoder service rate limit for the `myorg` organization.
The limit will be set at 100 requests per hour.
Note that even we're setting the default configuration for the whole organization,
the name of a user of the organization must be provided for technical reasons.
```
SELECT cdb_dataservices_client.cdb_service_set_org_rate_limit(
'myorgadmin',
'myorg',
'geocoder',
'{"limit":100,"period":3600}'
);
cdb_service_set_org_rate_limit
---------------------------------
(1 row)
```
#### cdb_dataservices_client.cdb_service_set_server_rate_limit(username, orgname, service, rate_limit)
This function sets the default rate limit configuration for all users accesing the dataservices server. This is overriden by organization of user configuration.
The configuration is provided as a JSON literal. To remove the organization-level configuration `NULL` should be passed as the `rate_limit`.
##### Returns
This functions doesn't return any value.
##### Example
This will configure the default geocoder service rate limit for all users
accesing the data-services server.
The limit will be set at 10000 requests per month.
Note that even we're setting the default configuration for the server,
the name of a user and the name of the corresponding organization (or NULL)
must be provided for technical reasons.
```
SELECT cdb_dataservices_client.cdb_service_set_server_rate_limit(
'myorgadmin',
'myorg',
'geocoder',
'{"limit":10000,"period":108000}'
);
cdb_service_set_server_rate_limit
---------------------------------
(1 row)
```