Examples

Here are some examples of setup to get you started. Please open an issue if you have a use case that is not included here.

The tests show a lot of different use cases that are not all covered here.

Apply a global (default) limit to all routes

    from starlette.applications import Starlette
    from slowapi import Limiter, _rate_limit_exceeded_handler
    from slowapi.util import get_remote_address
    from slowapi.middleware import SlowAPIMiddleware
    from slowapi.errors import RateLimitExceeded

    limiter = Limiter(key_func=get_remote_address, default_limits=["1/minute"])
    app = Starlette()
    app.state.limiter = limiter
    app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)
    app.add_middleware(SlowAPIMiddleware)

    # this will be limited by the default_limits
    async def homepage(request: Request):
        return PlainTextResponse("Only once per minute")

    app.add_route("/home", homepage)

Exempt a route from the global limit

    @app.route("/someroute")
    @limiter.exempt
    def t(request: Request):
        return PlainTextResponse("I'm unlimited")

Disable the limiter entirely

You might want to disable the limiter, for instance for testing, etc... Note that this disables it entirely, for all users. It is essentially as if the limiter was not there. Simply pass enabled=False to the constructor.

    limiter = Limiter(key_func=get_remote_address, enabled=False)

    @app.route("/someroute")
    @limiter.exempt
    def t(request: Request):
        return PlainTextResponse("I'm unlimited")

You can always switch this during the lifetime of the limiter:

    limiter.enabled = False

Use redis as backend for the limiter

limiter = Limiter(key_func=get_remote_address, storage_uri="redis://<host>:<port>/n")

where the /n in the redis url is the database number. To use the default one, just drop the /n from the url.

There are more examples in the limits docs which is the library slowapi uses to manage storage.

Set a custom cost per hit

Setting a custom cost per hit is useful to throttle requests based on something else than the request count.

Define a function which takes a request as parameter and returns a cost and pass it to the limit decorator:

    def get_hit_cost(request: Request) -> int:
        return len(request)

    @app.route("/someroute")
    @limiter.limit("100/minute", cost=get_hit_cost)
    def t(request: Request):
        return PlainTextResponse("I'm limited by the request size")

WSGI vs ASGI Middleware

SlowAPIMiddleware inheriting from Starlette's BaseHTTPMiddleware, you can find an alternative ASGI Middleware SlowAPIASGIMiddleware.
A few reasons to choose the ASGI middleware over the HTTP one are:

Starlette is probably going to deprecate BaseHTTPMiddleware
ASGI middlewares are more performant than WSGI ones
built-in support for asynchronous exception handlers
...

Both middlewares are added to your application the same way:

app = Starlette() # or FastAPI()
app.add_middleware(SlowAPIMiddleware)

app = Starlette() # or FastAPI()
app.add_middleware(SlowAPIASGIMiddleware)

Use view function's name instead of full endpoint as part of the storage key

Let's use this route as an example:

@app.route("/some_route/{some_param}")
def my_func(some_param):
    ...

limiter = Limiter(key_func=lambda: "mock", default_limits=["1/minute"], key_style="url")

When initializing the Limiter object with key_style="url", it will use the full endpoint url as part of the storage key.

When calling the /some_route/my_param endpoint would result with a key shaped like: LIMITER/mock//some_route/my_param/1/1/minute.

This means, that if the route contains some URL parameter, calling the endpoint with different parameters won't share the limitations.

limiter = Limiter(key_func=lambda: "mock", default_limits=["1/minute"], key_style="endpoint")

When initializing the Limiter object with key_style="endpoint", it will use the function name as part of the storage key.

When calling the /some_route/my_param endpoint would result with a key shaped like: LIMITER/mock/{module}.my_func/1/1/minute

This means, that if the route contains some URL parameter, calling the endpoint with different parameters will still share the limitations, since the view function is the same.

4.6 KiB Raw Blame History