Tutorial: Add Your First Endpoint¶

Walk through adding a complete feature to Reggie -- backend API endpoint, schema, tests, and TypeScript type sync.

What We'll Build¶

A simple GET /api/v1/health/detailed endpoint that returns system health with database connectivity status.

Step 1: Create the Route¶

Create backend/app/routes/health.py:

from fastapi import APIRouter, Depends
from sqlalchemy.orm import Session

from app.database import get_db
from app.schemas.health import DetailedHealthResponse

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


@router.get("/detailed", response_model=DetailedHealthResponse)
def detailed_health(db: Session = Depends(get_db)):
    """Detailed health check including database connectivity."""
    try:
        db.execute("SELECT 1")
        db_status = "connected"
    except Exception:
        db_status = "disconnected"

    return DetailedHealthResponse(
        status="healthy",
        database=db_status,
    )

Key patterns: - Always use Depends(get_db) for database sessions (never create manually) - Always use response_model so the endpoint appears in OpenAPI/Swagger - Tags group endpoints in the Swagger UI

Step 2: Create the Schema¶

Create backend/app/schemas/health.py:

from pydantic import BaseModel


class DetailedHealthResponse(BaseModel):
    status: str
    database: str

Step 3: Register the Route¶

In backend/app/main.py, add the router:

from app.routes.health import router as health_router

app.include_router(health_router, prefix=settings.API_V1_PREFIX)

Step 4: Add Tests¶

Create backend/tests/api/test_health.py:

import pytest
from httpx import AsyncClient


@pytest.mark.asyncio
async def test_detailed_health(async_client: AsyncClient):
    response = await async_client.get("/api/v1/health/detailed")
    assert response.status_code == 200
    data = response.json()
    assert data["status"] == "healthy"
    assert data["database"] == "connected"

Step 5: Run Tests¶

make test-backend

All tests should pass, including your new one.

Step 6: Sync TypeScript Types¶

Since you added a new Pydantic schema with a response_model, regenerate the TypeScript types:

npm run types:generate   # Backend must be running

This updates packages/api-client/src/generated/api.ts with your new DetailedHealthResponse type.

Step 7: Verify¶

Check http://localhost:8000/api/v1/docs -- your new endpoint appears under "health"
Try it in the Swagger UI
Run npm run typecheck to verify frontend types are clean

Summary¶

The pattern for any new feature:

Route in backend/app/routes/
Schema in backend/app/schemas/
Service in backend/app/services/ (for business logic)
Tests in backend/tests/
Type sync: npm run types:generate
Verify: make test-backend + npm run typecheck

See Add an API Endpoint for the full checklist.