Versioned routes

Contracts change. You add a field, rename another, change the shape of the trace. If your clients hit an unversioned endpoint, every change is a breaking change. A version prefix lets you ship a new contract behind a new path while the old one keeps working.

router.py
python
from fastapi import APIRouter, HTTPException

from models import ChatRequest, ChatResponse
from service import agent_service

router = APIRouter(prefix="/production-agent", tags=["production-agent"])


@router.get("/health")
async def health():
    """Basic liveness check."""
    return {
        "status": "healthy",
        "service": "production-agent-seven-layers",
        "layers": agent_service.layer_names(),
    }


@router.post("/chat", response_model=ChatResponse)
async def chat(request: ChatRequest):
    """Run a single user message through all seven layers and return the reply."""
    try:
        result = await agent_service.run(request.message, request.thread_id)
        return result
    except ValueError as e:
        raise HTTPException(status_code=400, detail=str(e))

The router lives behind a service prefix. To version, add /v1 inside that prefix and mount a new APIRouter when the contract changes. Health stays unversioned because it reports the service state, not user data.

Versioned route layout

Health is unversioned. User-facing endpoints live under a version prefix.

Flashcards: Flashcards

Loading practice…

Quiz: Quiz

Loading practice…

Checkpoint: Transport layer checkpoint

Loading practice…