API contracts break silently. Your React 19 frontend calls POST /users
expecting { id: string; email: string }
, but your FastAPI backend shipped { userId: number; userEmail: string }
. The request succeeds. The response doesn't match. Your frontend crashes in production, and you spend three hours in an incident call figuring out why a perfectly typed TypeScript component is receiving undefined properties.
I've lived this exact nightmare twice on CitizenApp—once before we shipped, once after. The second time cost us a customer's trust and three hours of developer velocity.
The fix isn't better testing or more code review. It's treating your API contract as the single source of truth and using Claude to generate both sides of it from natural language specifications, then validating that they match in CI before deployment. This is cursor-driven development done right: not mindless boilerplate generation, but intelligent contract enforcement that catches type mismatches across language boundaries.
Most full-stack developers reach for AI to generate TypeScript components or FastAPI route handlers. That's fine. But the real power is forcing your frontend and backend to negotiate a contract before either side exists. When you do this correctly:
I prefer this approach because it forces discipline. Too many teams use AI as a shortcut to avoid thinking about their API design. This pattern does the opposite: it requires you to think first, validate second.
Here's how it works on CitizenApp:
Let's build this end-to-end.
Feature: User Profile Update
Description: Allow authenticated users to update their profile metadata.
Fields: firstName (string, required), lastName (string, required), bio (string, optional, max 500 chars)
Validation: firstName and lastName must be at least 2 characters
Response: Returns updated user object with id, email, firstName, lastName, bio, updatedAt
Auth: Requires valid JWT in Authorization header
This goes in a file: specs/user-profile-update.md
Prompt your Cursor AI agent (or use Anthropic's API directly):
Given this spec, generate a FastAPI route with Pydantic schema.
Use SQLAlchemy ORM patterns.
Include validation decorators.
Output ONLY Python code, no explanation.
[paste spec here]
Claude outputs something like:
from pydantic import BaseModel, Field, field_validator
class UserProfileUpdateRequest(BaseModel):
firstName: str = Field(..., min_length=2, max_length=100)
lastName: str = Field(..., min_length=2, max_length=100)
bio: str | None = Field(None, max_length=500)
@field_validator("firstName", "lastName")
@classmethod
def validate_names(cls, v):
return v.strip()
class UserProfileResponse(BaseModel):
id: str
email: str
firstName: str
lastName: str
bio: str | None
updatedAt: str # ISO 8601
class Config:
from_attributes = True
python
from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.orm import Session
from .schemas import UserProfileUpdateRequest, UserProfileResponse
from .db import get_db
from .auth import get_current_user
router = APIRouter()
@router.put("/users/profile", response_model=UserProfileResponse)
async def update_user_profile(
request: UserProfileUpdateRequest,
current_user = Depends(get_current_user),
db: Session = Depends(get_db),
):
user = db.query(User).filter(User.id == current_user.id).first()
if not user:
raise HTTPException(status_code=404, detail="User not found")
user.firstName = request.firstName
user.lastName = request.lastName
if request.bio is not None:
user.bio = request.bio
db.commit()
db.refresh(user)
return user
You review this, tweak it if needed, and commit it. This is now your source of truth.
Different prompt:
Given this API spec and the Pydantic schemas below, generate:
1. TypeScript types matching the schemas (use zod or ts-pattern if validation needed)
2. A React 19 hook using useAsync or similar pattern
Use TanStack Query for mutations if appropriate.
Assume JWT is in Authorization header (handled by interceptor).
Pydantic schema:
[paste schema here]
API spec:
[paste spec here]
Claude outputs:
// types/user.ts
export interface UserProfileUpdateRequest {
firstName: string;
lastName: string;
bio?: string;
}
export interface UserProfileResponse {
id: string;
email: string;
firstName: string;
lastName: string;
bio?: string;
updatedAt: string;
}
js
// hooks/useUpdateUserProfile.ts
import { useMutation, useQueryClient } from "@tanstack/react-query";
export function useUpdateUserProfile() {
const queryClient = useQueryClient();
return useMutation({
mutationFn: async (
data: UserProfileUpdateRequest
): Promise<UserProfileResponse> => {
const response = await fetch("/api/users/profile", {
method: "PUT",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${localStorage.getItem("token")}`,
},
body: JSON.stringify(data),
});
if (!response.ok) {
throw new Error(`Failed to update profile: ${response.statusText}`);
}
return response.json();
},
onSuccess: (data) => {
queryClient.setQueryData(["user"], data);
},
});
}
This is where the magic happens. Create a Python script that introspects both:
import json
import subprocess
import sys
from typing import Any
def get_pydantic_schema(module_path: str, class_name: str) -> dict[str, Any]:
"""Extract JSON schema from Pydantic model"""
import importlib.util
spec = importlib.util.spec_from_file_location("module", module_path)
module = importlib.util.module_from_spec(spec)
spec..exec_module(module)
model_class = getattr(module, class_name)
return model_class.model_json_schema()
def get_typescript_types(file_path: str) -> dict[str, Any]:
"""Parse TypeScript types using TypeScript compiler API"""
result = subprocess.run(
["npx", "ts-json-schema-generator", "--path", file_path, "--type", "*"],
capture_output=True,
text=True,
)
return json.loads(result.stdout)
def validate_contract(python_schema: dict, ts_schema: dict) -> bool:
"""Ensure Python and TypeScript schemas match"""
py_props = python_schema.get("properties", {})
ts_props = ts_schema.get("properties", {})
for key, py_prop in py_props.items():
if key not in ts_props:
print(f"❌ Missing in TypeScript: {key}")
return False
py_type = py_prop.get("type")
ts_type = ts_props[key].get("type")
if py_type != ts_type:
print(f"❌ Type mismatch for {key}: Python={py_type}, TS={ts_type}")
return False
return True
if __name__ == "__main__":
py_schema = get_pydantic_schema("app/schemas.py", "UserProfileUpdateRequest")
ts_schema = get_typescript_types("src/types/user.ts")
if not validate_contract(py_schema, ts_schema):
sys.exit(1)
print("✅ Contract validated")
Add this to your GitHub Actions workflow:
- name: Validate API contracts
run: python scripts/validate_contracts.py
- name: Run tests
run: pytest app/ && npm test
Now, if someone changes a Pydantic field from str
to int
without updating the TypeScript type, the build fails before merging. This has saved us countless production incidents.
This burned me hard: I made a field optional in Pydantic (bio: str | None
) but forgot to mark it optional in TypeScript (bio: string
instead of bio?: string
). The validation passed because my naive script only checked required fields.
The fix: validate both presence and optionality:
python
def validate_contract(python_schema: dict, ts_schema: dict) -> bool:
py_required = set(python_schema.get