Version-Specific Response Schemas
What you'll learn: How to design response structures that evolve gracefully across API versions while maintaining compatibility with existing clients.
The Core Idea
When your AI API evolves, response formats must change too—new fields emerge, old ones become obsolete, and structures grow more sophisticated. Version-specific response schemas let different API versions return appropriately shaped data without breaking existing integrations.
Think of it like restaurant menus across different locations: the downtown branch might use detailed descriptions with nutritional info (v2), while the original location keeps simple item names (v1). Same kitchen, different presentations for different audiences.
Why This Matters
After establishing versioning strategies and backward compatibility principles, you need concrete implementations that return the right shape of data to each client. A v1 client shouldn't receive fields it doesn't understand, and a v2 client shouldn't be stuck with limited information just because v1 still exists.
Pattern in Practice
With Pydantic models (from lesson 975), you define separate schemas per version:
# v1 schema - simple response
class CompletionResponseV1(BaseModel):
text: str
model: str
# v2 schema - adds metadata
class CompletionResponseV2(BaseModel):
text: str
model: str
tokens_used: int
confidence_score: float
Your endpoint logic checks the requested version and serializes accordingly, ensuring clients only receive data in the structure they expect.
Managing Evolution
Start with v1 as your foundation. When adding v2, include all v1 fields plus new ones—never remove or rename without deprecation warnings. Use inheritance when possible to avoid duplication, but maintain separate response models for clarity.
Key Takeaway: Version-specific response schemas translate your API's evolution into concrete data structures, ensuring each client generation gets exactly the format it was built to handle—no more, no less.