About upgrading APIs
The Upgrading API feature provides a safe way to make significant changes to a published API without disrupting your existing consumers. Rather than editing a live API in place, you create a clone of it, make your changes freely, and run both APIs in parallel until you’re ready to fully cut over.
This is ideal for:
- Version upgrades — Roll out a new API version (e.g. v1 to v2) while giving consumers time to migrate
- Beta testing — Validate spec or configuration changes against real traffic before committing
- Breaking changes — Introduce changes that are incompatible with the current API without forcing an immediate cutover
- Spec redesigns — Restructure endpoints or payloads on a clean copy without risking the live API
- Certificate or security updates — Test new authentication configurations or trusted certificates in isolation before applying them to production traffic
You can also use the upgrade API flow to replace an existing API in-place. To do so, you will need to perform an additional step to retire the older API being replaced.
The typical workflow involves two steps:
- Clone the API — Create an editable copy of your existing published API
- Copy the access list — Transfer your original API’s subscribers to the new one so they don’t need to re-subscribe
- (Optional) Retiring the older API — If you intend to fully replace the original API with the cloned version, you must retire the original so that traffic routes correctly to the new API
