Course contentsShow
← AI Engineering
Lesson 1000 of 1,88624. Building AI APIsFree lesson

API Versioning Strategies

Compare URL, header, and query parameter versioning approaches for AI endpoints.

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.