Map your systems
Retiring APIs
Retire an API with a shutdown date and a replacement, and follow every consumer until they have all moved off.
Open Retiring APIs in the appWhat retiring an API does
Retiring (deprecating) marks a provider endpoint as retiring. You can give it a shutdown date, after which it counts as gone, and a replacement to move to.
The endpoint shows struck through, with a "Deprecated" badge and the days left, on the system page, the connection page and in the API catalog.
Retire an API
- Open the endpoint and choose Retire this API from the editor's more menu. Or open Retiring APIs in the sidebar (the Checks group), press Retire an API and pick the Endpoint.
- Set a Shutdown date, or press
+30d,+90dor+180d. - Choose the Replacement, if there is one.
- Write a Migration note that tells consumers what to do, such as
Use email-based login in v2. - Check the consumers listed under "These consumers will be notified".
- Optionally tick Create a migration epic with a sub-task per consumer to plan the work on the board.
- Press Retire the API.
To take it back, open the endpoint and choose Undo deprecation.
Deprecated on its own
When a release is deployed to Production and it brings a newer version of an endpoint (/api/v2/orders while /api/v1/orders is still there), the older versions are deprecated on their own. The replacement is the new version, the note says to use it, and there is no shutdown date: add one when you know it. Their history names the person who recorded the deployment.
This happens once, when the new version first reaches Production. If you undo the deprecation, it stays undone. You can still deprecate any endpoint yourself at any time, in Production or not, with or without a newer version.
What consumers see
- On the connection page, the provider row reads "Deprecated" with the days left.
- In the contract, a banner shows the note and the shutdown date. When there is a replacement, a button moves the expectation to it.
- The deprecation mismatch offers the quick fix Move to the replacement, which rewrites the expectation for the new endpoint.
Follow who has moved off
The Retiring APIs page lists every retiring API with:
- the days left, or "Shut down", and the shutdown date
- Moved off so far: how many of the consumers that used it when it was deprecated no longer do
- Still using it: each consumer that hasn't moved, with its team
- Moved off: the ones that have
For a consumer that is still using it:
- Remind them notifies its team, in the app, by email or on their webhooks, as each person chose (people who may manage deprecations).
- Ticket opens a migration ticket for it, or shows the one it has.
Below each API, How to move shows what is different between the old API and its replacement, and Change the API opens it (with the Edit endpoints permission).
Remove it safely
Remove the API only appears once every consumer has moved off and the page says "Everyone has moved off. Safe to remove." That way you don't remove an API someone still calls. It asks you to confirm, naming the endpoint, and needs permission to edit endpoints. Deprecating needs the Deprecate APIs permission; without it, Retire an API doesn't show.
Reminders
A daily job reminds people of a shutdown that is coming. It sends a notification 30, 14, 7 and 1 days before the shutdown date, and on the day itself, for each deprecated endpoint that still has consumers. It names the consumers that haven't moved. The last ones are marked breaking. See Notifications.
When automatic tickets are on, each consumer of a deprecated endpoint also gets a migration ticket that closes itself once the consumer stops calling it. See Ticket automation.
Related
- Versions and releasesRun API versions side by side, read the history and diff of every endpoint, create releases with a suggested version, and check old copies.
- Contract statusesWhat each status means, how one contract colours a connection and a system, how to read a contract, and how to tune the checks.
- NotificationsHear about the events that matter to you: in the app or by email, with a level for each kind of event.
- Automatic tickets and automationTickets that open and close themselves when a contract breaks, a test case fails or a service goes down, plus request tickets, access tickets and your own automation rules.
