What’s up with deprecated functions?

italic_tag Facebook has recently made some significant changes to the Platform, and in doing so has deprecated some functions from the API. Deprecation is a developer’s way of getting a do-over. A way to create something better than what’s there currently. However, if developers have applications that depend on those APIs, you can’t just yank them away. You need to to give some warning first, perhaps a transitional grace period, and then you can yank them away. Since the Facebook Platform is so volatile, it’s worth thinking about how to protect your applications in such an environment, and what we should be testing for.

Functions are deprecated for several reasons

There are generally 3 types of things that can have their features deprecated.

Libraries – such as Java and Windows
Standards – such as HTML
REST-oriented APIs – such as Facebook

The owners of these things will typically deprecate their features for one of three different reasons:

There’s a better way to do it

Once upon a time, if you wanted to have something centered on your page, you’d use a <center> tag to do it. With the advent of CSS, this is now considered to be very bad form, and so the tag has been deprecated.

The underlying implementation has changed which forces a redesign

The Java java.security.Certificate interface represents an abstraction to things like SSL and PGP certificates. As the world moves on and those objects change, holes start to form in this underlying abstraction until someone decides to create a whole new abstraction and deprecate the old one.

OMG! What were we thinking??

If you’ve been around long enough, you’ll be all too aware of the abomination known as the <blink> tag. Now the real truth is, this tag was actually never deprecated, but if any one deserves to be it’s this (well, and marquee too). Deprecated things like this allows developers to sweep their embarrassing stuff under the rug.

Enter Facebook

When a Java function is deprecated, life is pretty straight-forward for developers. The code will stop compiling, and alternate ways of doing things will need to be found (typically specified by the developer of the function). Deprecating an HTML tag is much more complex because it ultimately impacts the servers, clients, as well as the large amount of content that depends on the tag. Things will get broken, and there’s not much we can do about it – that’s the nature of things.

Facebook sits in the middle of this. Since Facebook APIs are ultimately just REST calls, there’s nothing to force your compilation to fail – hey, most Facebook apps aren’t even compiled to begin with. On the other hand, you don’t need to worry about every version of every browser out there. Your application deals with one Facebook server, and when that server’s interface changes, it’s important for you to take notice.

So what happens when you call a deprecated Facebook API?

Given that there’s a good possibility of apps out there that call deprecated functions, it’s important to ask what Facebook does when that happens. The short answer is that they return an error code – API_EC_DEPRECATED (= 11 for those keeping score). It is very important to check for this code and act on it if it’s ever returned. Remember, it’s Facebook’s sandbox, you just get to play in it so you better follow their rules. Calling a deprecated REST function is simply unnecessary, wastes resources, and ultimately will piss off the people who run the servers that your app relies on. Receiving an API_EC_DEPRECATED is akin to being told to “cut it out”. Of course, applications that don’t feel a need to follow the rules are always subject to the Developer Principles and Policies as well as the Terms of Use, things that we’re told are going to be increasingly enforced.

Protect your app

To protect your app, the correct attitude to take is to never be in a position where you receive an API_EC_DEPRECATED when you call a function. Here’s our 3 step plan for how to stay on Facebook’s good side:

Keep yourself informed. Know which functions are being deprecated by following all of the Facebook developer resources, and acting on the information.
Check your error codes. If there’s one thing that developers hate to do it’s checking the error codes. Make sure to do this, and if you ever get this, make sure the application does something to notify you.
Know your code. You may have written this app a year ago, but if it’s still available on Facebook, you need to check it. Get a list of all of the deprecated Facebook functions here. Use grep, or something similar to look through your code to see if you’re at risk.