Simulate API version management with endpoint mapping and deprecation scheduling. Part of the DevTools Surf developer suite. Browse more tools in the API / Config collection.
Use Cases
Plan a breaking API change without disrupting existing integrations
Model endpoint deprecation timelines with client migration windows
Evaluate URL vs header versioning strategies before implementation
Document version differences for API consumer communication
Tips
Map each version's endpoints and mark deprecated routes — the simulator shows which clients would break across a version transition
Configure the sunset date for deprecated endpoints; the tool generates Sunset and Deprecation headers per RFC 8594
Test version routing by simulating requests with different Accept-version or URL prefix patterns
Fun Facts
The three dominant API versioning strategies are URL path (/v1/resource), query parameter (?version=1), and custom header (Accept-Version: 1). URL path versioning is the most widely used, despite being considered least RESTful by purists.
Stripe's API is one of the few that versions by date (e.g., 2023-08-16) rather than integer version. Each customer's API version is pinned to their sign-up date, allowing backwards-compatible rollouts.
RFC 8594 'The Sunset HTTP Header Field' was published in 2019 to standardize deprecation signaling — 10+ years after versioning became a widespread API pattern, reflecting how long it took the industry to formalize the practice.
FAQ
Which versioning strategy is best?
URL versioning (/v1/) is easiest for developers to understand and test. Header versioning keeps URLs clean but requires header-aware clients. Date versioning (Stripe style) works well but needs robust pinning infrastructure.
When should I bump the API version?
For breaking changes: removing or renaming fields, changing data types, altering authentication, or removing endpoints. Adding new optional fields or endpoints is non-breaking and does not require a version bump.
How long should I maintain deprecated versions?
Industry norms range from 6 months (fast-moving startups) to 2+ years (enterprise APIs). Monitor actual usage of deprecated endpoints before sunsetting — some clients are slow to migrate.
