Retiring an API version without a surprise outage

You announce that v1 shuts down on the 31st, delete the routes that morning, and a customer you had forgotten finds out from their own error dashboard.

The email went out. The docs have a banner. Responses include a Deprecation header. Plenty of callers still miss all three: a cron job on a server nobody logs into, a mobile build that never picked up the update, an integration whose author has left. You hear about them when the calls start failing.

A date applies to every client at the same time, so you cannot pause it for the one account that needs another month. A flag on the v1 handler can. You already roll risky changes out and pull them back. Shutting down an API version is the same kind of change.

Gate the shutdown per client

Put one flag on the v1 handler and evaluate it with the calling client as context. Leave it on, then turn clients off in stages:

• Internal and test clients first, so you can watch the v2 path with callers you control.
• A small percentage of the remaining traffic. Those requests get a 410 Gone and a link to the migration guide.
• Everyone else, once the clients still calling v1 have either stopped or agreed a date.

import Featureflow from 'featureflow-node-sdk';

const featureflow = new Featureflow.Client({
  apiKey: process.env.FEATUREFLOW_SERVER_KEY,
  withFeatures: [new Featureflow.Feature('api-v1-enabled', 'on').build()],
});

app.use('/v1', (req, res, next) => {
  const client = Featureflow.UserBuilder
    .user(req.apiClient.id)
    .withAttribute('plan', req.apiClient.plan)
    .build();

  if (featureflow.evaluate('api-v1-enabled', client).isOn()) return next();

  res.status(410).json({ error: 'v1 retired', docs: MIGRATION_URL });
});

The failover value is on. If the SDK cannot fetch flag config, v1 keeps serving, so a problem reaching the flag service does not look like you turned the API off.

See who is still calling

Run a short brownout, something like 5% of traffic for an hour, and log every client id that receives the 410. Anyone who writes in still needs a migration plan. Anyone who keeps calling and never mentions it was not treating the error as a failure, so you have a better idea of who you can remove the routes for. If support hears from someone who should still be on v1, turn the flag back on for that client. It is a targeting change, and it does not need a deploy.

You can also write an explicit exception. A customer who needs v1 for another quarter gets an extra targeting rule for their client id. In Featureflow, that rule sits with the percentage rollout, and the audit trail records who changed it. The docs cover targeting by custom attributes.

Next time you retire an endpoint, put the flag on the handler before you publish a date. Leave v1 off for a full release cycle, then delete the flag and the old routes in the same change.

#FeatureFlags#APIDesign#ProgressiveDelivery#ContinuousDelivery#DevOps