Path Converters 🔄

Path converters allow FastAPI to automatically convert path parameters to specific types and validate them.

What are Path Converters?

Path converters are rules that transform URL path segments into Python objects. FastAPI handles this automatically using type hints.

Built-in Converters

String (Default)

@app.get("/items/{item_name}")
async def get_item(item_name: str):
    # item_name is always a string
    return {"item": item_name}

URL Examples:

• `/items/apple` → `item_name = "apple"`

• `/items/my-product` → `item_name = "my-product"`

Integer

@app.get("/items/{item_id}")
async def get_item(item_id: int):
    # item_id must be an integer
    return {"id": item_id}

URL Examples:

• `/items/123` → `item_id = 123` ✅

• `/items/abc` → Error 422 ❌

Float

@app.get("/coordinates/{latitude}")
async def get_location(latitude: float):
    return {"lat": latitude}

URL Examples:

• `/coordinates/40.7128` → `latitude = 40.7128` ✅

• `/coordinates/not-a-number` → Error 422 ❌

UUID

from uuid import UUID

@app.get("/users/{user_id}")
async def get_user(user_id: UUID):
    # Validates UUID format
    return {"user_id": user_id}

URL Examples:

• `/users/550e8400-e29b-41d4-a716-446655440000` ✅

• `/users/123` → Error 422 ❌

How Converters Work

from fastapi import FastAPI

app = FastAPI()

@app.get("/files/{file_id}")
async def get_file(file_id: int):
    '''
    FastAPI automatically:
    1. Extracts "file_id" from URL path
    2. Validates it's an integer
    3. Converts it to Python int
    4. Returns 422 if validation fails
    '''
    return {"file_id": file_id, "type": type(file_id).__name__}

Real-World Examples

# Product catalog with different parameter types
@app.get("/products/{product_id}")
async def get_product(product_id: int):
    # ID as integer
    return {"product_id": product_id}

@app.get("/search/{query}")
async def search(query: str):
    # Search term as string
    return {"search": query, "results": []}

@app.get("/prices/{price}")
async def filter_by_price(price: float):
    # Price as float for decimal values
    return {"min_price": price}

Type Hints Create Converters

from typing import Optional

@app.get("/users/{user_id}")
async def get_user(user_id: int):
    # This type hint: int
    # Automatically creates an integer converter
    # Works: /users/123
    # Fails: /users/abc
    return {"user_id": user_id}

Error Messages

When validation fails, FastAPI returns detailed error:

@app.get("/items/{item_id}")
async def get_item(item_id: int):
    return {"item_id": item_id}

# Request: GET /items/invalid
# Response: 422 Unprocessable Entity
# Detail: "value is not a valid integer"

🔑 Key Takeaways

• ✅ Type hints automatically create path converters

• ✅ `int`, `float`, `str`, `UUID` are common types

• ✅ FastAPI validates types automatically

• ✅ Invalid types return 422 error

• ✅ Converters happen before your function runs

• ✅ Use specific types for better validation

• ✅ UUID is great for IDs to ensure uniqueness