An API is a public contract: clients may depend on behaviors you never documented. Versioning lets you change that contract without breaking clients that still rely on the old one. section 6.12 section 6.3.4
Keep both menus open
A new orders format can live at GET /api/v2/orders while existing clients continue using GET /api/v1/orders. For a gradual alternative, clients can send a release-date header, such as Stripe-Version: 2024-09-14, to the same endpoint. Date-based versioning eases client migrations but adds server-side translation complexity. section 6.3.5
Choose an approach to fit the API:
- Use URI path versioning for internal services or smaller public APIs. section 6.3.5
- Consider date-based versioning when incremental updates for public consumers justify maintaining compatibility transformations. section 6.3.5



































