API Versioning Strategies
What you'll learn: How to choose between URL, header, and query parameter versioning for your AI API endpoints.
Why Versioning Matters for AI APIs
As your LLM application evolves, you'll need to change request/response structures, add new parameters, or modify behavior—all without breaking existing clients. API versioning creates a contract that lets you innovate while maintaining backward compatibility.
Three Core Versioning Approaches
URL Versioning
The version lives in the path itself: /v1/chat/completions vs /v2/chat/completions.
Pros: Immediately visible, easy to route in load balancers, clear in logs
Cons: Requires duplicate route definitions, can clutter your codebase
# FastAPI example
@app.post("/v1/completions")
async def completions_v1(request: CompletionRequestV1):
...
@app.post("/v2/completions")
async def completions_v2(request: CompletionRequestV2):
...
Header Versioning
The version comes in a custom HTTP header: API-Version: 2024-01-15 or Accept: application/vnd.myapi.v2+json.
Pros: Clean URLs, follows REST principles
Cons: Less visible, harder to test in browsers, requires header parsing logic
Query Parameter Versioning
The version appears as a parameter: /completions?version=2.
Pros: Easy to test, simple to implement
Cons: Mixes versioning with filtering parameters, can be accidentally omitted
Choosing Your Strategy
For AI APIs, URL versioning is most common because:
- Streaming responses and WebSocket upgrades are simpler with distinct paths
- Rate limiting and caching rules often differ by major version
- Developers can quickly test different versions without header manipulation
Header versioning works well when you need date-based versioning for rapidly evolving AI models where breaking changes are frequent but minor.
Key Takeaway: URL versioning (/v1/, /v2/) offers the clearest contract for AI APIs, making version differences explicit in routes, logs, and monitoring—critical when streaming behavior or model parameters change between versions.