FastAPI Router Acceptance Criteria

Skill: fastapi-router-py
Purpose: Create FastAPI routers with CRUD operations, authentication dependencies, and proper response models
Template: template.py

---

1. Router Creation Patterns

1.1 ✅ CORRECT: Basic Router Setup

from fastapi import APIRouter

router = APIRouter(prefix="/api", tags=["items"])

@router.get("/items")
async def list_items() -> list[ItemResponse]:
    """List all items."""
    return []

1.2 ✅ CORRECT: Router with Dependencies

from fastapi import APIRouter, Depends
from app.services.item_service import ItemService

router = APIRouter(prefix="/api", tags=["items"])

def get_service() -> ItemService:
    """Dependency to get service instance."""
    return ItemService()

@router.get("/items")
async def list_items(service: ItemService = Depends(get_service)):
    """List items using injected service."""
    return await service.list_items()

1.3 ❌ INCORRECT: Missing prefix or tags

# WRONG - no prefix definition
router = APIRouter()
# Missing tags make route organization unclear

---

2. HTTP Methods and Status Codes

2.1 ✅ CORRECT: Proper Status Codes

from fastapi import status

# GET - implicit 200
@router.get("/items/{item_id}", response_model=ItemResponse)
async def get_item(item_id: str) -> ItemResponse:
    """Get a single item."""
    return await service.get_item(item_id)

# POST - 201 Created
@router.post("/items", response_model=ItemResponse, status_code=status.HTTP_201_CREATED)
async def create_item(data: ItemCreate) -> ItemResponse:
    """Create a new item."""
    return await service.create_item(data)

# PATCH - 200 (partial update)
@router.patch("/items/{item_id}", response_model=ItemResponse)
async def update_item(item_id: str, data: ItemUpdate) -> ItemResponse:
    """Update an item."""
    return await service.update_item(item_id, data)

# DELETE - 204 No Content
@router.delete("/items/{item_id}", status_code=status.HTTP_204_NO_CONTENT)
async def delete_item(item_id: str) -> None:
    """Delete an item."""
    await service.delete_item(item_id)

2.2 ❌ INCORRECT: Wrong status codes

# WRONG - POST should be 201, not default 200
@router.post("/items")
async def create_item(data: ItemCreate):
    return await service.create_item(data)

# WRONG - DELETE should be 204, not 200
@router.delete("/items/{item_id}")
async def delete_item(item_id: str):
    await service.delete_item(item_id)

# WRONG - PATCH returning None without 204
@router.patch("/items/{item_id}")
async def update_item(item_id: str, data: ItemUpdate) -> ItemResponse:
    # Missing status_code for PATCH with return value
    return await service.update_item(item_id, data)

---

3. Response Models

3.1 ✅ CORRECT: Typed Response Models

from pydantic import BaseModel
from typing import Optional

class ItemResponse(BaseModel):
    """Response model for items."""
    id: str
    name: str
    description: Optional[str] = None
    created_at: str
    
    class Config:
        from_attributes = True

@router.get("/items", response_model=list[ItemResponse])
async def list_items() -> list[ItemResponse]:
    """List items."""
    return await service.list_items()

@router.get("/items/{item_id}", response_model=ItemResponse)
async def get_item(item_id: str) -> ItemResponse:
    """Get single item."""
    return await service.get_item(item_id)

3.2 ❌ INCORRECT: Missing or wrong response models

# WRONG - no response_model specified
@router.get("/items")
async def list_items():
    # Doesn't define return type schema
    return await service.list_items()

# WRONG - response_model doesn't match return type
@router.get("/items", response_model=ItemResponse)
async def list_items() -> list[ItemResponse]:
    # Should be response_model=list[ItemResponse]
    return await service.list_items()

# WRONG - using dict instead of Pydantic model
@router.get("/items", response_model=dict)
async def list_items() -> dict:
    # Should use typed Pydantic models
    return {}

---

4. Authentication Patterns

4.1 ✅ CORRECT: Optional Authentication

from typing import Optional
from fastapi import Depends

@router.get("/items", response_model=list[ItemResponse])
async def list_items(
    current_user: Optional[User] = Depends(get_current_user),
) -> list[ItemResponse]:
    """List items. Authentication optional."""
    # Anyone can call this, but authenticated users may get more data
    return await service.list_items(user_id=current_user.id if current_user else None)

4.2 ✅ CORRECT: Required Authentication

from fastapi import Depends

@router.post("/items", response_model=ItemResponse, status_code=status.HTTP_201_CREATED)
async def create_item(
    data: ItemCreate,
    current_user: User = Depends(get_current_user_required),  # Required
) -> ItemResponse:
    """Create item. Authentication required."""
    return await service.create_item(data, owner_id=current_user.id)

4.3 ✅ CORRECT: Query Parameters with Validation

from fastapi import Query

@router.get("/items", response_model=list[ItemResponse])
async def list_items(
    limit: int = Query(default=50, ge=1, le=100, description="Max items to return"),
    offset: int = Query(default=0, ge=0, description="Items to skip"),
) -> list[ItemResponse]:
    """List items with pagination."""
    return await service.list_items(limit=limit, offset=offset)

4.4 ❌ INCORRECT: Authentication mistakes

# WRONG - using string instead of dependency
@router.post("/items")
async def create_item(data: ItemCreate, current_user: str):
    # Should use Depends(get_current_user_required)
    pass

# WRONG - Optional auth on write operation
@router.post("/items")
async def create_item(
    data: ItemCreate,
    current_user: Optional[User] = Depends(get_current_user),  # Should be required
):
    return await service.create_item(data)

# WRONG - Hardcoding user ID
@router.post("/items")
async def create_item(data: ItemCreate):
    # Missing authentication entirely
    return await service.create_item(data, owner_id="hardcoded-user")

---

5. Error Handling

5.1 ✅ CORRECT: Proper HTTPException Usage

from fastapi import HTTPException, status

@router.get("/items/{item_id}", response_model=ItemResponse)
async def get_item(item_id: str) -> ItemResponse:
    """Get item by ID, with error handling."""
    item = await service.get_item(item_id)
    if item is None:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="Item not found",
        )
    return item

@router.patch("/items/{item_id}", response_model=ItemResponse)
async def update_item(
    item_id: str,
    data: ItemUpdate,
    current_user: User = Depends(get_current_user_required),
) -> ItemResponse:
    """Update item with ownership check."""
    existing = await service.get_item(item_id)
    if existing is None:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="Item not found",
        )
    
    if existing.owner_id != current_user.id:
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail="Not authorized to update this item",
        )
    
    return await service.update_item(item_id, data)

5.2 ❌ INCORRECT: Poor error handling

# WRONG - returning None instead of raising exception
@router.get("/items/{item_id}")
async def get_item(item_id: str):
    item = await service.get_item(item_id)
    return item  # Returns None on missing item, no 404

# WRONG - bare exception
@router.post("/items")
async def create_item(data: ItemCreate):
    try:
        return await service.create_item(data)
    except Exception:
        return {"error": "Failed"}  # Wrong! Should use HTTPException

# WRONG - wrong status code
@router.delete("/items/{item_id}")
async def delete_item(item_id: str):
    if not await service.exists(item_id):
        raise HTTPException(
            status_code=status.HTTP_200_OK,  # WRONG - should be 404
            detail="Item not found",
        )

---

6. Async Patterns

6.1 ✅ CORRECT: Async Endpoints

@router.get("/items", response_model=list[ItemResponse])
async def list_items(service: ItemService = Depends(get_service)) -> list[ItemResponse]:
    """All endpoints should be async."""
    return await service.list_items()

@router.post("/items", response_model=ItemResponse, status_code=status.HTTP_201_CREATED)
async def create_item(
    data: ItemCreate,
    service: ItemService = Depends(get_service),
) -> ItemResponse:
    """Create with async service call."""
    return await service.create_item(data)

6.2 ❌ INCORRECT: Synchronous endpoints

# WRONG - using def instead of async def
@router.get("/items")
def list_items(service: ItemService = Depends(get_service)):
    # FastAPI endpoints should be async for concurrent handling
    return service.list_items()

# WRONG - blocking operation without await
@router.post("/items")
async def create_item(data: ItemCreate):
    # If service is async, must use await
    return service.create_item(data)  # Missing await

---

7. Dependencies and Imports

7.1 ✅ CORRECT: Proper Imports

from typing import Optional
from fastapi import APIRouter, Depends, HTTPException, Query, status

from app.auth.jwt import get_current_user, get_current_user_required
from app.models.user import User
from app.models.item import ItemResponse, ItemCreate, ItemUpdate
from app.services.item_service import ItemService

7.2 ✅ CORRECT: Consistent Dependency Pattern

def get_service() -> ItemService:
    """Dependency to get service instance."""
    return ItemService()

@router.get("/items")
async def list_items(service: ItemService = Depends(get_service)):
    """Using dependency injection pattern."""
    return await service.list_items()

7.3 ❌ INCORRECT: Import mistakes

# WRONG - importing from wrong module
from fastapi.responses import JSONResponse
# Should use response_model parameter

# WRONG - creating service inline instead of via dependency
@router.get("/items")
async def list_items():
    service = ItemService()  # Should use Depends(get_service)
    return await service.list_items()

# WRONG - forgetting authentication function
@router.post("/items")
async def create_item(data: ItemCreate, current_user: User):
    # Missing: Depends(get_current_user_required)
    pass

---

8. Path Parameters

8.1 ✅ CORRECT: Typed Path Parameters

from typing import Annotated
from fastapi import Path

@router.get("/items/{item_id}", response_model=ItemResponse)
async def get_item(
    item_id: Annotated[str, Path(description="Unique item ID")]
) -> ItemResponse:
    """Get item by ID."""
    return await service.get_item(item_id)

# Or simpler form
@router.get("/items/{item_id}", response_model=ItemResponse)
async def get_item(item_id: str) -> ItemResponse:
    """Get item by ID."""
    return await service.get_item(item_id)

8.2 ❌ INCORRECT: Path parameter mistakes

# WRONG - untyped path parameter
@router.get("/items/{item_id}")
async def get_item(item_id):
    # Should have type annotation
    return await service.get_item(item_id)

# WRONG - path parameter name mismatch
@router.get("/items/{id}")
async def get_item(item_id: str):
    # Parameter name doesn't match path: {id} vs item_id
    pass

---

9. Documentation

9.1 ✅ CORRECT: Docstrings and Descriptions

from typing import Annotated
from fastapi import Query

@router.get(
    "/items",
    response_model=list[ItemResponse],
    summary="List all items",
    description="Retrieve a paginated list of all items in the system.",
)
async def list_items(
    limit: Annotated[int, Query(ge=1, le=100, description="Max items per page")] = 50,
    offset: Annotated[int, Query(ge=0, description="Items to skip")] = 0,
) -> list[ItemResponse]:
    """
    List items with pagination.

    - **limit**: Maximum number of items to return (1-100)
    - **offset**: Number of items to skip for pagination
    """
    return await service.list_items(limit=limit, offset=offset)

9.2 ❌ INCORRECT: Missing documentation

# WRONG - no docstring
@router.get("/items")
async def list_items():
    return await service.list_items()

# WRONG - unclear descriptions
@router.get("/items", response_model=list[ItemResponse])
async def list_items(limit: int = Query(default=50)) -> list[ItemResponse]:
    # No docstring, parameter description unclear
    return await service.list_items(limit=limit)

---

10. Router Mounting

10.1 ✅ CORRECT: Mounting in Main App

# In routers/items.py
from fastapi import APIRouter

router = APIRouter(prefix="/api/v1", tags=["items"])

@router.get("/items")
async def list_items():
    return []

# In main.py
from fastapi import FastAPI
from routers.items import router as items_router

app = FastAPI(title="My API")
app.include_router(items_router)

10.2 ❌ INCORRECT: Router mounting mistakes

# WRONG - prefix duplication
# In routers/items.py
router = APIRouter(prefix="/api/items")

# In main.py
app.include_router(items_router, prefix="/api")  # Results in /api/api/items

# WRONG - forgetting to mount router
# In main.py
from routers.items import router
# Missing: app.include_router(router)
# Routes won't be registered

---

11. Query Parameters

11.1 ✅ CORRECT: Query Parameter Validation

from fastapi import Query
from typing import Annotated, Optional

@router.get("/items", response_model=list[ItemResponse])
async def list_items(
    skip: Annotated[int, Query(ge=0, description="Items to skip")] = 0,
    limit: Annotated[int, Query(ge=1, le=100, description="Max items")] = 50,
    search: Annotated[Optional[str], Query(min_length=1, max_length=100)] = None,
) -> list[ItemResponse]:
    """List items with optional search and pagination."""
    return await service.list_items(skip=skip, limit=limit, search=search)

11.2 ❌ INCORRECT: Query parameter mistakes

# WRONG - no validation
@router.get("/items")
async def list_items(limit: int = 50):
    # No validation; limit could be negative or huge
    return await service.list_items(limit=limit)

# WRONG - query in path
@router.get("/items/{search}")  # Should be query parameter
async def search_items(search: str):
    return await service.search(search)

---

12. Complete Router Example Checklist

• [ ] Router has prefix and tags
• [ ] All endpoints are async def
• [ ] Each endpoint has response_model specified
• [ ] POST returns status.HTTP_201_CREATED
• [ ] DELETE returns status.HTTP_204_NO_CONTENT
• [ ] Authentication required for write operations (POST, PATCH, DELETE)
• [ ] Error handling with appropriate HTTPException status codes
• [ ] Query parameters have validation (Query with ge, le, etc.)
• [ ] Path parameters are typed
• [ ] Service is injected via Depends()
• [ ] Docstrings on all endpoints
• [ ] Imports from correct modules (fastapi, app.*, etc.)
• [ ] No hardcoded values (user IDs, secrets, etc.)

---

13. Anti-Patterns Summary

Anti-Pattern	Impact	Fix
Using def instead of async def	Blocks event loop, poor concurrency	Change to async def
Missing response_model	OpenAPI schema wrong, validation skipped	Add response_model=YourModel
Wrong status codes	Confuses clients, breaks contracts	Use status.HTTP_* constants
Missing error handling	500 errors on invalid requests	Use HTTPException
Authentication on wrong endpoints	Security vulnerability or UX issue	Required for writes, optional for reads
Service creation inline	Hard to test, couples logic	Use Depends(get_service)
No parameter validation	Invalid data accepted	Use Query(), Path() with constraints
Untyped responses	Poor API documentation	Always specify response_model