Deprecation

Deleting an endpoint is fast and someone else pays for it. Deprecating it is the alternative: the endpoint stays in the spec, everyone who reads the documentation sees that it is going away and by when, and there is a written answer to "what do I use instead". Routebase turns that into a dated plan with phases, reminders and an approval step, rather than a checkbox somebody flips.

Two things to be clear about before the details, because they decide what this feature can and cannot do for you:

• A deprecation plan is a contract statement, not a traffic control. Routebase does not sit in front of your production API, so nothing here throttles or blocks a real consumer. What it does is publish the intent — in your spec, in your portal, in the OpenAPI you export — and track the deadline.
• The one place behaviour does change is the Routebase mock server. If your consumers develop against a Routebase mock, the plan's sunset policy is applied there. That is described under Sunset policy.

The phases

A deprecation moves through phases rather than flipping from "fine" to "gone". Seven exist:

stateDiagram-v2
    state "Pending approval" as PA
    state "Announced" as AN
    state "Grace period" as GP
    state "Sunset phase" as SP
    state "Retired" as RT
    state "Rejected" as RJ
    state "Cancelled" as CX

    [*] --> PA: org policy requires approval
    [*] --> AN: no approval required
    PA --> AN: an admin approves
    PA --> RJ: an admin declines
    AN --> GP: automatic, at once
    GP --> SP: automatic, when the window opens
    SP --> RT: by hand — unless Automatic Shutdown is on
    PA --> CX
    AN --> CX
    GP --> CX

Phases advance on their own — a background job checks every hour and moves plans on when their dates come due, announcing the transition as it goes. You do not have to click anything for a plan to progress from announced to grace period to sunset.

Retirement is the one exception, and it is deliberate. A plan is only retired automatically if you turned on Automatic Shutdown when you created it. Otherwise it sits in the sunset phase past its sunset date, waiting for a human. The reasoning is that "the date passed" and "we are ready to remove it" are different statements, and only one of them is safe to make from a timer.

Creating a plan

Open the endpoint in the API Designer. The Deprecated toggle in the editor header is the quick way to mark something as on its way out — it sets the flag in the spec and nothing else. For an endpoint consumers actually call, use the deprecation wizard, which turns that flag into a plan with a date.

The wizard has five steps:

1. Sunset Date — when the endpoint stops being available. This is validated against your organization's minimum grace period; a date that is too soon is refused with the number of days required.
2. Successor — search your endpoints by method or path and pick the one that replaces this one, or leave it empty when the endpoint is simply going away. The successor travels with the deprecation, so a consumer reading the docs sees where to go next. Your organization can make this mandatory.
3. Migration Guide — instructions for the people who have to change their code. This is the part that decides whether a deprecation is a courtesy or a nuisance. Required by default; a template is offered as a starting point.
4. Sunset Policy — what happens as the date approaches. See below.
5. Review — the whole plan on one screen before anything is announced.

You can step back to any completed step from the progress indicator at the top.

Sunset policy

Three switches, all of which take effect in the sunset phase and all of which apply to requests against a Routebase mock server for this endpoint:

• Deprecation Warning Header — adds an RFC 7234 Warning: 299 header naming the sunset date and, where one is set, the successor endpoint. Note that the Deprecation and Sunset headers are sent regardless of this switch, as soon as the plan has a sunset date; this switch adds the human-readable warning on top.
• Reduced Rate Limiting — cuts the mock rule's rate limit by the percentage on the slider for the whole sunset phase, and marks throttled responses with X-RateLimit-Deprecated: true. The cut happens in one step when the phase begins; it does not ramp up towards the sunset date. This only does something if the mock rule already has a rate limit configured; without one there is nothing to reduce.
• Automatic Shutdown — retires the plan on its own once the sunset date passes, instead of leaving it for a person. Its soft shutdown window is the number of days before sunset in which the mock starts answering 410 Gone instead of the normal response, so consumers hit the removal in testing before they hit it in production.

If your consumers do not use a Routebase mock, leave these off; they will not do anything.

Approval

When your organization requires approval, a new plan starts in Pending approval and the endpoint is not yet deprecated. The endpoint's deprecation panel says so explicitly, and offers an admin Approve and Reject — rejection requires a comment.

Approval moves the plan to announced and starts the clock. Rejection is terminal: the plan is closed and a new one has to be created.

Watching a plan

The endpoint's Deprecation panel in the designer shows the live state: the phase, the sunset date, the successor, and two numbers worth explaining:

• Usage (last 30 days) — request counts and unique consumers.
• Migration progress — how far usage has fallen from the first day the plan was tracked to the most recent one, as a bar.

Both numbers count requests against the Routebase mock server only. They are a good signal when your consumers develop against your mocks, and they are silent about production traffic, because Routebase never sees it. A migration progress of 100% means nobody is calling the mock any more — not that nobody is calling your API.

Alongside them, Routebase flags a plan whose usage has been zero for 14 consecutive days, which is the closest thing to an "it is safe to remove this" signal the data can give.

The deprecation dashboard

Settings → Governance (Pro and above, org:manage-governance) carries a Deprecation Dashboard across the whole organization: totals per phase, and every plan grouped into sunset phase, grace period and announced, ordered by urgency. Selecting one opens its details.

Changing, cancelling, and retiring

From the endpoint's deprecation panel you can:

• Edit the sunset date and the migration guide while the plan runs.
• Cancel the plan. The endpoint stays and the deprecation disappears from the portal.

Retiring a plan by hand — for a plan that is past its sunset date without automatic shutdown — is available through the API and the MCP tool retire_deprecation.

Retiring records that the deprecation ran its course. It does not delete the endpoint from your spec; removing it is a separate, deliberate edit, and one that is a breaking change.

What consumers see

On a published portal, a deprecated endpoint's page carries a banner with the sunset date, the number of days remaining, the rendered migration guide, and a link to the successor where one is set. This is why the migration guide is worth writing properly: it is the text a consumer reads at the moment they discover the problem.

The banner is controlled by the Show deprecation info switch in your portal settings, and only announced (not pending) plans reach it. See Portal Branding for the portal's feature switches.

Consumers on your team are also notified: an announcement notification when the plan goes live, and sunset reminders at 30, 14, 7 and 1 days before the date by default.

Organization policy

Settings → Deprecation Policy (org:manage-governance) sets the floor for every deprecation in the organization — so one person cannot rush one through on a Friday afternoon.

Start from a preset and adjust:

The individual settings behind them:

• Minimum grace period — the shortest allowed gap between announcement and sunset. A wizard that proposes a closer date is refused.
• Sunset phase — how many days before the sunset date the sunset phase begins.
• Require migration guide / Require successor link — make those wizard steps mandatory.
• Require approval — whether plans start in pending approval.
• Notify on announcement and Send sunset reminders, with the reminder schedule as a set of checkboxes (60, 30, 14, 7, 3, 1 days before sunset).