Automated Deprecation Detection: Coming Soon to an RFC Near You

So, I got my druthers in bunch and decided that the Internet really needed a new standard. So I wrote one.

I build APIs for a living (thats Application Programming Interface to everyone else.) Part of the horror of what I do for a living is cleaning up after tenures of really bad decision making. It is a daily thing for me now.

But as I continuously support these horrid ideas that people previous to myself (and, well, including myself if I am to be quite honest) part of the issue is trying to correct the errors of our ways. The problem, however, is that once you publish a public interface you’re kinda stuck with it. Because people can then use it and write software that depends on your (lets be honest) crappy implementations.

Publicly, all software engineers say our stuff is keen and clean while privately we panic almost daily when we dig up one of our long forgotten gems we thought was a really great idea at the time. Now it stares back at us as we wonder, “What in the hell was I thinking?” If only it were easier to fix things that are publicly facing. If only there was a way to let your customers know about breaking changes and the newer, better way to use your services before they actually break.

Enter Automated Deprecation Detection.

The gist of the RFC I have authored is to introduce a whole new HTTP status code: 286 Deprecated. The whole point of this code is to behave like a 200 OK status code while alerting clients that the service they depend upon may be going away or changing at some time in the future. The 286 Deprecated status code is accompanied by header metadata that indicates when a resource will be removed and where more information about that deprecation can be found.

The idea is that software engineers write software to automate the things we don’t want to monitor ourselves (shocker, I know….) and may actually miss the feeble attempts of API maintainers to warn us of impending doom. But now with the introduction of the 286 status code clients can check for it and alert their maintenance teams accordingly, so that they know well in advance that a dependency will be break before it actually does.

I can’t tell you how awesome this is, unless you’ve ever written any software that depends on some 3rd party system, which was deprecated at some point in a blog like this and you didn’t happen to be reading the blog that day. Then one day, you’re sipping on your coffee and all things are grand, when all of the sudden–WHHHAAAPAA–your shit stops working.

For the laypeople who happen to be gluttons for punishment, when an HTTP client makes a request to an external system they’re usually looking for a 200 OK response code that says, “Yup, I know what the hell you’re asking for and here it is!” But until now there was no way–outside of posting in a changelog blog or sending warning messages when no one is actually listening–that the service being requested was being removed or replaced with anything else.

286 Deprecated means “Ok, but what you’re asking for is being 86d in the near future.” This status code now lets software engineers look for the 2xx SUCCESS portion of the code, but notice the x86 portion of the code which says, “Okay, BUT…” and then let the people who wrote that software know to look into it before it becomes a coffee-spoiling, day-ruining thang.

Of course none of this is official yet. The RFC has been submitted for editorial review and it is up to the IETF to determine if this is as awesome as I say it is or not. But I have my hopes. And I think we very well may be looking at RFC#### in the near future.

Believe me, when that day comes I’ll let everybody know.