Parameters

In this section, we will explore how to extract and validate HTTP parameters using Rapidy.

Basics of Data Extraction and Validation

To validate and extract data from an incoming HTTP request, Rapidy uses its internal data types — rapidy parameters.

The example below extracts and validates a dynamic path variable user_id and the header Host:

from rapidy.http import get, PathParam, Header

@get('/{user_id}')
async def handler(
    user_id: int = PathParam(),
    host: str = Header(alias='Host'),
) -> ...:

What is a rapidy parameter?

A rapidy parameter is a meta-object that contains information on how parameters from an incoming HTTP request should be extracted.

All rapidy parameters are located in the rapidy.parameters.http module:

from rapidy.parameters.http import Header, Cookie, QueryParam, ..., Body

async def handler(
    user_id: int = QueryParam(),
) -> ...:
    ...

They can also be accessed via the rapidy.http module:

from rapidy.http import Header, Cookie, QueryParam, ..., Body

async def handler(
    user_id: int = QueryParam(),
) -> ...:
    ...

HTTP Request Parameters

You can learn more about each parameter type in the corresponding sections:

• Path — path parameters (used for creating dynamic APIs)
• Headers — request header parameters
• Cookies — cookie parameters (automatically extracted from headers)
• Query Parameters — query parameters passed in the URL
• Body — request body parameters

Data Extraction

Data can be extracted using either the rapidy parameter's attribute name or its alias.

Extraction using attribute name

from rapidy.http import QueryParam

async def handler(
    test_query_param_name: int = QueryParam(),
) -> int:
    return test_query_param_name

curl -G -v -d "test_query_param_name=123456789" http://127.0.0.1:8080
# < HTTP/1.1 200 OK ...
# 123456789

Extraction using alias

from rapidy.http import QueryParam

async def handler(
    test_query_param_name: int = QueryParam(alias='TestQueryParamName'),
) -> int:
    return test_query_param_name

curl -G -v -d "TestQueryParamName=123456789" http://127.0.0.1:8080
# < HTTP/1.1 200 OK ...
# 123456789

Validation Capabilities

Each rapidy parameter inherits from pydantic.Field and supports all of its features.

@get('/')
async def handler(
    positive: int = QueryParam(gt=0),
    non_negative: int = QueryParam(ge=0),
    negative: int = QueryParam(lt=0),
    non_positive: int = QueryParam(le=0),
    even: int = QueryParam(multiple_of=2),
    love_for_pydantic: float = QueryParam(allow_inf_nan=True),
    short: str = QueryParam(min_length=3),
    long: str = QueryParam(max_length=10),
    regex: str = QueryParam(pattern=r'^\d*$'),
    precise: Decimal = QueryParam(max_digits=5, decimal_places=2),
) -> ...:
    ...

Parameter Annotation Methods

Defining a Parameter as a Default Value

The simplest and most intuitive way to define a parameter:

from rapidy.http import get, PathParam

@get('/{user_id}')
async def handler(
    user_id: int = PathParam(),
) -> ...:
    ...

However, if you use static code analyzers like mypy, you might encounter errors:

main.py:4: error: Incompatible default for argument "user_id" (default has type "PathParam", argument has type
"int")  [assignment]

To prevent this, enable the mypy plugin for Rapidy:

# pyproject.toml
[tool.mypy]
plugins = [
    "pydantic.mypy",
    "rapidy.mypy"     # <-- enable Rapidy plugin
]

Annotation Using typing.Annotated

You can read more about typing.Annotated in the official Python documentation here.

from typing import Annotated
from rapidy.http import get, PathParam

@get('/{user_id}')
async def handler(
    user_id: Annotated[int, PathParam()],
) -> ...:
    ...

The Annotated annotation uses two key arguments:

• The first argument Annotated[int, ...] defines the expected data type (in this case, int).
• The last argument Annotated[..., PathParam()] must be one of the Rapidy HTTP parameters (Header, Headers, Cookie, ..., Body). In this case, the server expects the Host header.

Since Annotated can accept an unlimited number of parameters, Rapidy explicitly takes only the first and last arguments for validation. Other parameters may be used as metadata for the validation model in pydantic, if supported, to perform additional type checks.

Missing HTTP Parameters in Annotated

If Annotated does not contain an HTTP parameter, such as Annotated[str, str], the attribute will be ignored.

Support for Default Values

Header(default=..., default_factory=...)

You can read more about default values in the corresponding section of each HTTP parameter.