Create a version and deprecate one

Before you start#

Your product is published in Studio and the change you need is breaking (what counts as breaking). A change that is not breaking goes into the current version.

Steps#

1. In Studio, create the new major version of the product and publish it. Its routes are created under /v<n>/, next to the old version's.
2. Tell your subscribers what changed and how to move.
3. Request the deprecation of the old major version. The platform reviews the request.
4. When the platform approves it, the removal date is set to 30 days later and every subscriber of the old version is notified.
5. On the removal date the old version's routes are removed.

Check that it worked#

Both versions answer until the removal date. After it, a call to the old version's path returns 404 with no Route matched with those values.

If something goes wrong#

• A subscriber still on the old version after the removal date gets 404: there is no grace period after the date.
• If 30 days is too short for your subscribers, publish the new version well before you request the deprecation.