API Versioning

Three primary approaches exist. URI versioning (/v1/, /v2/) is the most common: clients explicitly specify the version in every request URL. Simple and highly visible, but routes the team must maintain in parallel grow with each major version. Header versioning (API-Version: 2024-01-01) keeps the URL clean and allows date-based versioning (Stripe's model), where each API version is named after a date and customers are upgraded to new defaults on their own account anniversary. Query parameter versioning (?version=2) is the simplest but often considered least clean. Most SaaS APIs use URI versioning for public APIs. Regardless of mechanism, the key commitments to customers are: how long will old versions be supported? (industry standard is 12–24 months after a new version is released); how are breaking changes defined and communicated? (a formal definition of "breaking change" prevents debates during deprecation); and what is the migration path? (provide clear migration guides with code examples).

API deprecation is a customer trust event — done poorly, it generates significant negative sentiment even when the underlying product improvement is positive. Best practice for SaaS API deprecation: announce deprecation 12+ months in advance (minimally 6 months for low-usage endpoints); provide a concrete sunset date (ambiguous deprecation timelines create false security); send targeted notifications to every customer actively using the deprecated endpoint (identifiable from API logs — "Dear [Company], our records show you are calling /v1/users — this endpoint will sunset on [date]. Here's how to migrate:"); publish a detailed migration guide with before/after code examples; offer a compatibility mode or shimming period where the new version translates from the old schema; and create a deprecated endpoint usage dashboard visible to customers in their admin settings, showing their usage and the time remaining.

API deprecations reliably generate support ticket surges — customers migrate at the last minute, integration issues surface, and some customers miss the deprecation entirely. Mitigation strategies: sunset in waves rather than all at once (disable for a randomly selected 5% of affected customers two weeks before the full sunset, so issues surface with a manageable volume before the full impact); staff up support for the deprecation window (schedule additional agent hours in the two weeks before and after the sunset date); pre-build a Zendesk macro with the migration guide and common error solutions, enabling rapid first-touch resolution by Tier 1 agents without engineering escalation; create a dedicated "API Migration" Zendesk view so these tickets are triaged by your most technically capable agents; and post a real-time status update on your developer status page for the sunset day, with monitoring for migration-related error spikes.