The right way to turn off your old APIs

A fun fact: for my previous job I developed a set of libraries to make Node API development type safe and generally easy to use safely with a lot of help from the TS compiler. When I got the chance to prove it out for production use, I was tasked (well I volunteered) with porting a service that had one of the worst API designs I’ve ever encountered. It had no design, totally off the cuff for every route handler. But it was in production and critical, and API stability was a hard requirement.

A wonder of wonders: these libraries worked with almost no rework, mapped to an internal implementation that was much better to work with, and auto generated documentation that was 99% correct (I fixed the two bugs filed over 10 months).

Before I left we were planning a v2 API, and as far as I could tell literally no business logic/service code would need to change. Only the service boundaries.

And on my way out, doing knowledge transfer sessions, all the things that seemed inscrutable about the libraries doing all that work really clicked with the rest of my team. It was already doing the API translation that was the ugly part. Once they saw how it worked with APIs that were designed for use and development, nothing felt painful for the team I was leaving it with.

Planning ahead for this kind of thing is important. You don’t have to have the perfect API. You just have to have good abstractions in place for the inevitability you don’t have the perfect API.

I feel like there is one important detail missing. There is no way to turn off an API like this without guaranteeing not to introduce breakage. Even for a well behaved client that has enough foresight to anticipates API deprecation.

You only get the specified headers AFTER calling the API endpoint.

So for example if a device sits in a drawer for a year, then calls the API your response is undefined if the API has been turned off. No chance to get the date beforehand.

The way I handled situations like this is to explicitly make 'turned off' part of every single API response.

Something like APIResponse = SpecificResponseForEndpoint | TurnedOff

That way API interactions are always well defined, clients can implement a global handler that does the appropriate thing, locking the client in a 'please update' state if it is an in house developed app for example.

For HTTP I usually reserve the 410 status code for that since it usually does not collide with the more common 404.

> first they disabled it for one hour, then reenabled it, then they disabled it permanently two weeks later.

> There's other tricks too: Android added increasing delays to deprecated native APIs in 2015, eventually going up to a full 16 second wait, before finally turning off the API entirely.

I feel that this is the crux. You never know who actually uses the API until it is really unavailable.

Last week I was fixing a bug caused by vendor who had updated an API in an incompatible way (probably via a shim of some sort) this was causing our shared ultimate end customer to be at risk of regulatory fines. Thankfully as it turns out the last 1.xx version of the API was mostly adding functionality we don't use and we can swap to using a new field without lots of pain.

However this does mean we need to spend a couple of weeks of developer and tester time retesting the interface code. Cost I would guess $10,000 by the time we add in all the PM/PO/DevOps time multiply that by a few customers and it adds up fairly quickly.

Moving to version 2.xx doesn't look too bad but the monolithic protobuf file has been split into parts and the upgrade is probably going to take a 6-8 weeks as they've also changed some of the enum values and properly deprecated stuff. My gut feel from having spent a couple of hours looking at V2.xx is it mostly compatible but this vendor has form for hiding a surprise change (they changed from representing money as an int with an implied decimal place to a long+int)

Again probably not too much work overall but it will cost $20,000 to swap versions and the opportunity cost of not doing something else instead.

We have the same problem with the API for external applications we provide. We know folks are running very elderly versions (over 3 years old) and our next version is huge change for client applications. We've taken advantage of this change to rename a load of stuff and explicitly add types in various places. I doubt we'll be able to sunset the old API for many years.

Google did this with their old Helm chart repository.

If your API is simple enough that it can be reimplemented as a shim to the new API, and that shim layer needs no state or special permissions, then it becomes effectively maintanance free. Your shim cannot have security issues (since it has no special permissions). It likely won't have scaling issues (no state makes scaling easy). You can leave it sitting there forever if necessary, and the total cost will be well below the risks of turning off an external API.