Course contentsShow
← Cloud and Infrastructure
Lesson 548 of 2,98910. API Gateway and Event-Driven PatternsFree lesson

API Versioning Strategies

Implement API versioning using path-based, header-based, or stage-based approaches for backward compatibility.

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.