FastAPI Router Templates: Build REST APIs with Best Practices Baked In

Building REST APIs shouldn't require reinventing the wheel for every resource. The FastAPI Router skill provides battle-tested templates for creating API endpoints with authentication, proper response models, HTTP status codes, and CRUD patterns already figured out—so you can focus on business logic instead of boilerplate.

What This Skill Does

The fastapi-router-py skill offers templates and patterns for building FastAPI routers that follow best practices right out of the box. It provides standardized CRUD endpoint patterns (create, read, update, delete), authentication dependency injection patterns for both optional and required auth, proper response model annotations for OpenAPI documentation, correct HTTP status codes for all operations, and integration guidance for connecting routers to your main FastAPI application.

This isn't a library you import—it's a template and pattern guide. Copy the template, replace the placeholders with your resource names, and you have a production-ready router with authentication, validation, error handling, and documentation built in.

Getting Started

The skill assumes you have a FastAPI project structure. Here's a typical setup:

src/
├── backend/
│   └── app/
│       ├── main.py              # FastAPI application entry
│       ├── routers/             # API route handlers
│       │   ├── __init__.py
│       │   ├── items.py
│       │   └── users.py
│       ├── models/              # Pydantic models
│       └── services/            # Business logic

Start by copying the router template and replacing placeholders:

• {{ResourceName}} → PascalCase (e.g., Item, Project, User)
• {{resource_name}} → snake_case (e.g., item, project, user)
• {{resource_plural}} → plural form (e.g., items, projects, users)

Here's a complete example router for managing projects:

from fastapi import APIRouter, Depends, HTTPException, status
from typing import Optional
from ..models.project import Project, ProjectCreate, ProjectUpdate
from ..dependencies.auth import get_current_user, get_current_user_required
from ..models.user import User

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

@router.get("/", response_model=list[Project])
async def list_projects(
    current_user: Optional[User] = Depends(get_current_user)
) -> list[Project]:
    """List all projects. Returns only user's projects if authenticated."""
    # Business logic here
    return projects

@router.get("/{project_id}", response_model=Project)
async def get_project(
    project_id: str,
    current_user: User = Depends(get_current_user_required)
) -> Project:
    """Get a specific project. Authentication required."""
    # Fetch from database
    project = await fetch_project(project_id)
    
    if not project:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="Project not found"
        )
    
    # Check ownership
    if project.owner_id != current_user.id:
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail="Not authorized to access this project"
        )
    
    return project

@router.post("/", status_code=status.HTTP_201_CREATED, response_model=Project)
async def create_project(
    project: ProjectCreate,
    current_user: User = Depends(get_current_user_required)
) -> Project:
    """Create a new project. Authentication required."""
    new_project = await create_project_service(project, current_user.id)
    return new_project

@router.patch("/{project_id}", response_model=Project)
async def update_project(
    project_id: str,
    updates: ProjectUpdate,
    current_user: User = Depends(get_current_user_required)
) -> Project:
    """Update an existing project. Authentication required."""
    project = await fetch_project(project_id)
    
    if not project:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="Project not found"
        )
    
    if project.owner_id != current_user.id:
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail="Not authorized to update this project"
        )
    
    updated_project = await update_project_service(project_id, updates)
    return updated_project

@router.delete("/{project_id}", status_code=status.HTTP_204_NO_CONTENT)
async def delete_project(
    project_id: str,
    current_user: User = Depends(get_current_user_required)
):
    """Delete a project. Authentication required."""
    project = await fetch_project(project_id)
    
    if not project:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="Project not found"
        )
    
    if project.owner_id != current_user.id:
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail="Not authorized to delete this project"
        )
    
    await delete_project_service(project_id)
    # No return value for 204 No Content

Mount the router in your main application:

# src/backend/app/main.py
from fastapi import FastAPI
from .routers import projects

app = FastAPI()
app.include_router(projects.router)

That's the pattern: define endpoints, apply authentication dependencies, use response models, return proper status codes.

Key Features

Two Authentication Patterns: The templates provide two auth dependency patterns. Use get_current_user (returns Optional[User]) for endpoints that work both authenticated and unauthenticated—behavior changes based on auth state. Use get_current_user_required (returns User) for endpoints that require authentication—FastAPI automatically returns 401 Unauthorized if not authenticated.

Response Model Annotations: Every endpoint declares its response_model. This generates accurate OpenAPI/Swagger documentation automatically, validates response data at runtime, and enables IDE autocomplete for API consumers. FastAPI uses these annotations to serialize responses correctly.

Proper HTTP Status Codes: The templates use semantically correct status codes: 200 OK for successful reads and updates, 201 Created for successful creates, 204 No Content for successful deletes, 404 Not Found when resources don't exist, 403 Forbidden for authorization failures, and 422 Unprocessable Entity for validation errors (handled automatically by FastAPI).

CRUD Patterns: Complete create, read, update, delete patterns with proper error handling. Each endpoint checks existence, validates permissions, and returns appropriate errors. This is production-ready code, not placeholder examples.

OpenAPI Documentation: With response models, tags, and docstrings, FastAPI generates interactive API documentation at /docs (Swagger UI) and /redoc (ReDoc). No extra configuration needed—it just works.

Usage Examples

Optional Authentication (Public + Authenticated Behavior):

@router.get("/articles", response_model=list[Article])
async def list_articles(
    current_user: Optional[User] = Depends(get_current_user)
) -> list[Article]:
    """List articles. Shows drafts if authenticated."""
    if current_user:
        # Authenticated: show all including drafts
        return await fetch_all_articles(user_id=current_user.id)
    else:
        # Public: show only published
        return await fetch_published_articles()

Pagination with Query Parameters:

from fastapi import Query

@router.get("/items", response_model=list[Item])
async def list_items(
    skip: int = Query(0, ge=0),
    limit: int = Query(100, ge=1, le=1000),
    current_user: User = Depends(get_current_user_required)
) -> list[Item]:
    """List items with pagination. Authentication required."""
    items = await fetch_items(
        user_id=current_user.id,
        skip=skip,
        limit=limit
    )
    return items

Partial Updates with PATCH:

from pydantic import BaseModel
from typing import Optional

class ItemUpdate(BaseModel):
    title: Optional[str] = None
    description: Optional[str] = None
    is_active: Optional[bool] = None

@router.patch("/{item_id}", response_model=Item)
async def update_item(
    item_id: str,
    updates: ItemUpdate,
    current_user: User = Depends(get_current_user_required)
) -> Item:
    """Partially update an item. Only provided fields are updated."""
    item = await fetch_item(item_id)
    
    if not item:
        raise HTTPException(status_code=404, detail="Item not found")
    
    if item.owner_id != current_user.id:
        raise HTTPException(status_code=403, detail="Not authorized")
    
    # Only update provided fields
    update_data = updates.dict(exclude_unset=True)
    updated_item = await update_item_service(item_id, update_data)
    
    return updated_item

Filtering with Query Parameters:

@router.get("/tasks", response_model=list[Task])
async def list_tasks(
    status: Optional[str] = Query(None, regex="^(todo|in_progress|done)$"),
    priority: Optional[int] = Query(None, ge=1, le=5),
    current_user: User = Depends(get_current_user_required)
) -> list[Task]:
    """List tasks with optional filtering."""
    filters = {}
    if status:
        filters["status"] = status
    if priority:
        filters["priority"] = priority
    
    tasks = await fetch_tasks(user_id=current_user.id, filters=filters)
    return tasks

Custom Response Status Codes:

@router.post("/{item_id}/archive", status_code=status.HTTP_202_ACCEPTED)
async def archive_item(
    item_id: str,
    current_user: User = Depends(get_current_user_required)
):
    """Archive an item asynchronously. Returns 202 Accepted."""
    item = await fetch_item(item_id)
    
    if not item:
        raise HTTPException(status_code=404, detail="Item not found")
    
    # Queue background job
    await queue_archive_job(item_id)
    
    return {"message": "Archive job queued", "item_id": item_id}

Best Practices

Use Response Models Always: Don't skip response_model declarations. They catch serialization errors early, generate accurate documentation, and make your API contract explicit. FastAPI's automatic validation prevents you from accidentally returning the wrong data.

Separate Create and Update Models: Use different Pydantic models for POST (create) and PATCH (update) operations. Create models have all required fields; update models have all optional fields. This makes validation clear and prevents partial creates.

Implement Ownership Checks: Always verify the current user owns the resource before allowing updates or deletes. Don't rely on URL parameters alone—validate ownership against the database.

Use Specific Exception Messages: Don't return generic "Not found" or "Forbidden" errors. Be specific: "Project not found", "Not authorized to delete this project". This helps debugging and improves user experience.

Tag Your Routers: Use tags parameter in APIRouter() to group related endpoints in API documentation. This makes the auto-generated docs much more navigable.

Write Docstrings: Every endpoint should have a docstring. FastAPI includes these in OpenAPI documentation as endpoint descriptions. Future you (and your API consumers) will thank you.

Test Authentication Paths: Write tests for both authenticated and unauthenticated access to every endpoint. Ensure 401/403 errors return correctly and that optional auth endpoints behave properly in both states.

When to Use This Skill

Perfect for:

• Building new REST API endpoints following team standards


• Quickly scaffolding CRUD operations for new resources


• Ensuring consistent authentication patterns across APIs


• Onboarding new developers with proven patterns


• Refactoring inconsistent API endpoints to match standards


• Prototyping APIs with proper structure from the start

Less relevant for:

• GraphQL APIs (different paradigm)


• WebSocket or SSE endpoints (different protocol)


• Projects without authentication needs (though patterns still useful)


• Non-FastAPI Python frameworks

The router templates save time and prevent bugs by encoding best practices into reusable patterns. Use them as your starting point, then customize for specific business logic.

Related Skills

Explore the full FastAPI Router skill: /ai-assistant/fastapi-router-py

Source

This skill is provided by Microsoft as part of internal API development patterns.

---

Building REST APIs? Start with proven patterns instead of reinventing the wheel.