4 ms·

> informing users of the deprecation If you can get users to take notice from the start of the fact that your API has the possibility of spitting out certain ‘

by derefr 6y ago

> informing users of the deprecation If you can get users to take notice from the start of the fact that your API has the possibility of spitting out certain ‘temporary errors’ that “MUST” trigger a client-side retry with backoff (e.g. 429 errors) — and your API does actually emit these errors sometimes, such that clients' codebases are very likely to have this error-handling code in place — then you’re in a much better situation here: you can give deprecations like these technical force, by making deprecated APIs begin to randomly emit spurious failures, with the failure self-documenting with a response error message like “usage of this API has been deprecated and will gradually cease to function. [link to blog post about transitioning to new API]” Start off with allowing 99% of requests through; then lower it following a sigmoid, e.g. 95%; 90%; 66%; etc; until eventually it’s at some low number like 1%. Wait a few months at 1%, and then turn it off. (And, obviously, email every user who your metrics say are still using the deprecated API, each time you ratchet it down, to nudge them once again to update their code.) Any app developer who doesn’t notice that your API is now requiring ~100 retries to contact successfully, either isn’t using the results for anything; or just plain isn’t around any more to update their app, such that the app is now abandonware. Either way, you’re likely safe to shut off the API at that point, and finally clean up that code. Of course, you can also make side-deals with any big enterprise user who needs more time, putting their API keys on a whitelist so that they'll get 100% success from the API until the very end. (Try not to allow them to slip the sunset date for the API, though; that would force you to keep the code around longer, which is what you're trying to avoid!)

cpeterso 6y ago
Or gradually increase the API latency so the system still produces correct results but the users are increasingly motivated to upgrade to the new API. I like the idea of encouraging clients to handle API errors more robustly, but the type of client developers that are slow to upgrade to the new API might also write sloppy code. Their client will break but they’re likely to blame your service.
- derefr 6y ago
  The problem with just adding artificial latency, is that it makes it unclear why latency is increasing. Users may think "maybe the upstream service is just gaining users and failing to scale." The great thing about an error, is that it gets your users' users upset (without really impacting them materially, if you're only doing them 1% of the time), in a way that tends to get your user to sit down and debug the problem. When they open their logs, they'll see your service's deprecation notice in each error message. If you're already thinking about this when designing your API response envelope format, you could have a "warnings" field to put information like that in. But a lot of devs are going to miss that entirely, because they've got your API wrapped in a gateway object that strips out everything but the data they're interested in for "successful" responses. They'll only actually pass any of the envelope stuff through in the case of an error.
  - cpeterso 6y ago
    That's a good point. An API error can include an error message explaining the problem (and solution!) to the client developer. You've changed my mind. :)

by derefr 6y ago

cpeterso 6y ago

Or gradually increase the API latency so the system still produces correct results but the users are increasingly motivated to upgrade to the new API. I like the idea of encouraging clients to handle API errors more robustly, but the type of client developers that are slow to upgrade to the new API might also write sloppy code. Their client will break but they’re likely to blame your service.

derefr 6y ago
The problem with just adding artificial latency, is that it makes it unclear why latency is increasing. Users may think "maybe the upstream service is just gaining users and failing to scale." The great thing about an error, is that it gets your users' users upset (without really impacting them materially, if you're only doing them 1% of the time), in a way that tends to get your user to sit down and debug the problem. When they open their logs, they'll see your service's deprecation notice in each error message. If you're already thinking about this when designing your API response envelope format, you could have a "warnings" field to put information like that in. But a lot of devs are going to miss that entirely, because they've got your API wrapped in a gateway object that strips out everything but the data they're interested in for "successful" responses. They'll only actually pass any of the envelope stuff through in the case of an error.
- cpeterso 6y ago
  That's a good point. An API error can include an error message explaining the problem (and solution!) to the client developer. You've changed my mind. :)