Strategies for API Versioning

Once an API is consumed by third-party clients or mobile applications, you can no longer introduce breaking changes. Versioning is your only escape hatch.

• URL Versioning (e.g., /api/v1/users) is the most common and explicit method. It is incredibly easy to route via reverse proxies but can lead to duplicated code if not structured properly.
• Header Versioning keeps URLs clean by requiring clients to pass an Accept-Version header. This follows REST principles more closely but is harder to test in a standard browser.
• Stripe popularized the concept of date-based versioning at the edge. They maintain one core backend application and use request middleware to mutate incoming and outgoing payloads to match the specific version the client requested.