Skip to content

How To: Add an API Endpoint

Steps

  1. Route in backend/app/routes/ -- define the HTTP handler
  2. Schema in backend/app/schemas/ -- Pydantic request/response models
  3. Service in backend/app/services/ -- business logic (if non-trivial)
  4. Register the router in backend/app/main.py
  5. Tests in backend/tests/api/
  6. Run tests: make test-backend
  7. Sync types: npm run types:generate (backend must be running)
  8. Verify frontend: npm run typecheck

Critical Patterns

Always use dependency injection for database sessions: 

@router.get("/endpoint")
def endpoint(db: Session = Depends(get_db)):
    return db.query(Model).all()

Always normalize plate registrations: 

from app.utils.registration import normalize_registration

reg = normalize_registration(user_input)  # Uppercases, strips spaces/dashes

Auth dependencies: 

from app.utils.auth import get_current_user, require_admin

@router.get("/protected")
def protected(user=Depends(get_current_user)):
    ...

@router.get("/admin-only")
def admin_only(user=Depends(require_admin)):
    ...

Always set response_model so the endpoint appears correctly in OpenAPI and TypeScript types are generated.

After Adding

What you changed Run this
Route or schema make test-backend + npm run types:generate
Model (database) make test-backend + make test-backend-pg + create migration
Frontend consuming new types npm run typecheck + npm run build