API Versioning Strategies
What you'll learn: You'll discover three practical approaches to version your APIs so you can evolve them without breaking existing clients.
Why Version Your APIs?
As your API evolves—adding features, changing data structures, or fixing design flaws—you need a way to introduce changes without disrupting clients still using the old version. API versioning is like maintaining both the old and new editions of a book simultaneously so readers can choose which one they need.
Three Common Versioning Approaches
Path-Based Versioning
Include the version directly in the URL path:
/v1/users
/v2/users
This is the most visible and explicit method. Clients know exactly which version they're calling just by looking at the URL. It works naturally with API Gateway stages and route configurations.
Header-Based Versioning
Specify the version in a custom HTTP header:
GET /users
X-API-Version: 2
This keeps URLs clean but requires clients to include the correct header. Your API Gateway can route requests based on header values using request validation and mapping templates.
Stage-Based Versioning
Use API Gateway stages to represent versions:
https://api.example.com/prod/users (v2)
https://api.example.com/v1/users (v1)
Stages provide built-in environment separation (like we learned in "API Gateway Stages and Deployment") and allow stage variables to toggle backend behavior per version.
Choosing Your Strategy
Path-based is easiest to understand and cache. Header-based keeps URLs stable but adds complexity. Stage-based leverages cloud provider features but may mix versioning with environment concepts.
Key Takeaway: API versioning strategies—path-based, header-based, or stage-based—enable backward compatibility by letting old and new API versions coexist, ensuring existing clients continue working while you innovate.