Parameters

Warning

The current page still doesn't have a translation for this language.

But you can help translating it: Contributing.

Lilya supports Query, Header, and Cookie parameters to cleanly and declaratively extract data from HTTP requests.

1. What each parameter type is
2. Why and when to use them
3. Benefits of Lilya's parameter system
4. How to declare and inject them

---

What Are Request Parameters?

• Query Parameters: Key‑value pairs in the URL after ?, used for filtering, searching, pagination, and optional flags.
• Header Parameters: Metadata in HTTP headers (like Authorization, X‑API‑TOKEN), used for authentication, content negotiation, and custom flags.
• Cookie Parameters: Key‑value pairs stored in cookies, used for sessions, CSRF tokens, user preferences, and stateful data.

---

✅ Why Use Them?

• Separation of concerns: Clearly distinguish URL modifiers (query) from metadata (headers) and state (cookies).
• Type safety: Lilya casts and validates values automatically.
• Declarative design: Declare parameters in your function signature, not inside your handler code.
• Consistency: Uniform API for all parameter types with required, default, alias/value, and cast options.

---

Benefits of Lilya's Parameter System

• Clean signatures: No manual extraction from request; Lilya handles it.
• Automatic validation: Missing required fields or invalid types immediately return 422.
• Rich metadata: Control required, set default or alias/value, and perform runtime cast.
• Unified API: Same workflow for Query, Header, and Cookie with minimal boilerplate.

---

Declaration Syntax

Query

from lilya.params import Query

async def handler(
    q: str = Query(default=None, alias="q", required=False, cast=str)
):
    ...

Option	Type	Description
default	Any	Fallback if not present
alias	str	Query key name in URL
required	bool	Whether to enforce presence
cast	type	Callable to convert raw string

---

Header

from lilya.params import Header

async def handler(
    token: str = Header(value="X-API-TOKEN", required=True, cast=str)
):
    ...

Option	Type	Description
value	str	Header key name (required)
required	bool	Whether to enforce presence
cast	type	Callable to convert raw string

---

Cookie

from lilya.params import Cookie

async def handler(
    session: str = Cookie(value="csrftoken", required=True, cast=str)
):
    ...

Option	Type	Description
value	str	Cookie name (required)
required	bool	Whether to enforce presence
cast	type	Callable to convert raw string

---

🔍 Real‑World Examples

1. Basic Query Injection

async def search_books(query: str = Query()) -> dict:
    return {"query": query}

GET /search?query=python

2. Header‑Based Auth

async def get_user(
    token: str = Header(value="Authorization", required=True)
) -> dict:
    return {"user": validate_token(token)}

GET /profile
Authorization: Bearer TOKEN123

3. Cookie‑Based Session

async def dashboard(
    session_id: str = Cookie(value="sessionid", required=True)
) -> dict:
    return {"session": load_session(session_id)}

GET /dashboard
Cookie: sessionid=abc123

4. Combined Query, Header, Cookie, Body, Dependency

from lilya.params import Query, Header, Cookie
from lilya.dependencies import Provide
from pydantic import BaseModel

class User(BaseModel):
    name: str
    age: int

class Service:
    def show(self):
        return "ok"

async def handle(
    user: User,                          # from JSON body
    q: str = Query(alias="q", default="none"),
    token: str = Header(value="X-TOKEN", required=True),
    session: str = Cookie(value="csrftoken"),
    svc: Service = Provide(Service)      # injected dependency
):
    return {
        "user": user.model_dump(),
        "q": q,
        "token": token,
        "session": session,
        "svc": svc.show(),
    }

Request example:

GET /?q=hello
Headers: X-TOKEN: tok
Cookies: csrftoken=sess
Body: {"name": "tiago", "age": 35}

---

Summary

• Query: URL-based filters/flags
• Header: HTTP metadata
• Cookie: Client‑stored data
• Declare with Query, Header, Cookie in signature
• Control required, default, alias/value, and cast
• Combine freely with path, body, and dependencies