Your development team has created a new version of their service's API. You need to deploy the new versions of the API with the least disruption to third-party developers and end users of third…

The standard practice for API versioning to minimize disruption is to introduce the new API as a distinct, concurrently available version. Once the new version is available and stable, then you can announce the deprecation of the old version, providing third-party developers and applications ample time to migrate without immediate breakage, ensuring backward compatibility for a period.

Announcing deprecation before introducing the new API creates a period where users might not have a supported path forward, leading to disruption and uncertainty.

Announcing deprecation and contacting users without providing the new API first leaves users in a limbo state, unable to migrate, causing significant disruption.

Contacting remaining users of the old API should happen after deprecation is announced and the new API is available, providing them with a clear path and deadline for migration, rather than immediately after introduction.