dataservices-api/doc/rate_limits.md

# 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)
```