RabbinatixDocs
Sign inGet started

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 app

What 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.

WhenWhat consumers get
From the moment you deprecate itTheir contract gets ENDPOINT_DEPRECATED, a warning, and turns Warning if it was Healthy
After the shutdown dateTheir contract gets ENDPOINT_SUNSET, which is breaking, and turns Broken

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

  1. 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.
  2. Set a Shutdown date, or press +30d, +90d or +180d.
  3. Choose the Replacement, if there is one.
  4. Write a Migration note that tells consumers what to do, such as Use email-based login in v2.
  5. Check the consumers listed under "These consumers will be notified".
  6. Optionally tick Create a migration epic with a sub-task per consumer to plan the work on the board.
  7. 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.

TipTo retire a whole API version, check API versions & adoption on the Releases page (pick the system) to see who is still on it, then deprecate each of its endpoints.

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.