The short video Why Stripe’s API Never Breaks introduces how Stripe handles API versioning. Stripe's API URLs do not include a (consequential) version number and yet every API release is supported. Instead,
- The API client includes in each HTTP requests a header with the client's API release date, eg "X-Stripe-Version: 2024-01-23".
- Stripe's API server transforms the dated request into a current version request.
- Stripe's API server transforms the current version response into the dated response.
This does mean that each new API release needs transformers for all previous releases. I suspect that there are few breaking changes and most transformers default to the previous release's transformers.
Using a version HTTP header does not seem different than using a version number in the URL path, but there is something elegant about maintaining stable URLs across API versions. It also seems easer in most web frameworks (eg Rails) to introduce the transformers after routing.
