8. Rate Limiting

You can use rate limiting with Synful to control how often certain parts of your API are allowed to be accessed.

⚠ You must install the php-apcu package to enable Rate Limiting in Synful.

Synful uses the Token Bucket Algorithm for handling rate limiting.

---

Rate Limiting specific parts of Synful

You can configure what sections have rate limiting applied under the Rate.json configuration file.

Areas that currently support Rate Limiting

Area	Application
Global	All requests from a specific IP
API Key	All requests from a specific IP using a specific API key
Request Handler	All requests from a specific IP to a specific Request Handler

---

Applying Rate Limiting on a Global Scope

To apply rate limiting to all requests entering your API, first enable the global flag in Rate.json and then configure the global_rate_limit.

Example

This example will set a 5 requests per 1 second rate limit for all requests entering the system.

"global": true,

. . .

"global_rate_limit": {
    "requests": 5,
    "per_seconds": 1
}

Hint: Set all rate limits to 0 requests per 0 seconds to make them unlimited.

---

Applying Rate Limiting to a specific Request Handler

To apply rate limiting to specific Request Handlers, first enable the per_handler flag in Rate.json.

Inside your Request Handler you will need to define the rate limit.

Example

This example will set a 10 requests per 1 second rate limit for the specified Request Handler.

class MyRequestHandler extends RequestHandler
{
    /**
     * The rate limit for this RequestHandler.
     */
    public $rate_limit = [
        'requests'    => 10,
        'per_seconds' => 1,
    ];
}

---

Applying Rate Limiting to a specific API Key

To apply rate limiting to specific Request Handlers, first enable the per_key flag in Rate.json.

When you generate your API Key, you will need to supply the rate_limit and the rate_limit_per_seconds parameters. These are the last two parameters of the command.

Example

This example will create the following key:

Belongs To: Test Key
    Auth Handle    : TEST
    Whitelist-Only : false
    Security       : Level 10
    Rate Limit     : 5 Requests / 1 seconds
    Enabled        : true

./synful -ck MYTEST 'Test Key' 10 0 5 1

Hint: Set all rate limits to 0 requests per 0 seconds to make them unlimited.

---

Rate Limit Error Codes

Code	Error
1028	Global rate limit exceeded.
1029	Endpoint rate limit exceeded.
1030	API Key rate limit exceeded.
1031	Attempting to load APCu for RateLimit but php-apcu extension not installed.

---

Next: Custom Function Libraries