In working on the StumbleUpon Safari extension, I came across requests in the SU support forums about SU providing an API for developers to create SU toolbars of their own. Currently there is a Firefox plugin provided by StumbleUpon but that’s it as far as actual extensions available for SU functionality. They created a toolbar that essentially puts the stumbles into an iframe but that’s fragile and can be broken by sites that have code expressly to break out of iframes. And there are other limitations too, limitations that the Firefox plugin lacks. Limitations which could be overcome in other browsers if only the private API used in the Firefox plugin were made available to all. I’ve stared tackling the task of breaking code out of the Firefox plugin for use elsewhere but I’m still left wondering whether I should.

Ask the Right Question

Keep in mind, there are two questions to ask here. One is whether it’s a good idea. The other is whether I have a right to do so. Reusing a private API has some pretty nasty downsides. Since it is private, the interface isn’t likely to be documented. You’re going to be spending time looking at message traffic, poring over all of the usage in their code to see what sorts of return values are checked. And if the developers of the private API get upset over your usage of their API they could change things such that you will be forced to extensively redevelop your version just to keep up. In cases where, as with the StumbleUpon extension, communication with a server is required, it gets worse because now you’re dealing with their servers and interfaces there which they define. In my case, I’m actually rewriting their private API, essentially recreating code to reuse their protocol. While it’s unlikely they would change the protocol extensively, since that could alienate Firefox users, it’s not outside the realm of possibility.

So why do it? If you’re considering using a private API, it’s likely because that is the only way to do what you want to do. Left with another choice, most developers would typically prefer to use a well documented public API if one is available since the drawbacks are far fewer. There are cases, though, where there are both public and private APIs available and the public API provides less power than the private APIs. This seems to tend to happen when the APIs are provided by a single vendor who also provides applications which make use of the APIs. Their apps can make use of the private APIs, resulting in more features than any third party app can provide.

Really, it seems like this is just a judgement call. Are you crazy enough to want to ride this train? Do you really want to risk pissing off the developers who created the private API, such that you end up having to rewrite your app from scratch just because they got a bee in their bonnet about its use? Heck, that could happen even if they don’t know your name. It might have been a planned revision. The fact is, you have no promises. But if you want to create your project badly enough, maybe you’re just crazy enough.

A Question of Right or Wrong

The other question is of the rightness or wrongness of using the private APIs. Of course there may be legal ramifications but that’s not what I’m talking about. Let me give you an example. With MiniStumble, I’m using the StumbleUpon API to retrieve stumble URLs from their servers. That makes use of their bandwidth, CPU and power. This may be miniscule, but it all adds up. Additionally, consider that they make money off of what they call paid discovery, where advertisers can pay to inject a URL into the stumble lineup for certain categories. What happens, then, if some rogue extension grabs URLs and never reports back that they were visited? SU would not be able to report the proper number of visitors sent to that site which begins to mess with their revenue stream. That is not being a good neighbor.

As it happens, the SU servers appear not to serve up additional stumbles until previous stumbles are reported as having been visited, so there is some sanity checking that goes on, and I’m aware enough of at least that part of what SU does to try to avoid being a prick about things anyway, but it could have been a problem. The Firefox plugin for SU is not the most complex software I’ve seen, but the code paths are many and it is easy to lose track of where different pieces of functionality will wind up taking you. In the process of trying to rewrite or just reuse a private API, you could be underdelivering to the original API writer’s customers. You might be creating problems for the API writer’s business. In short, maybe you shouldn’t have been doing what you are doing in the first place.

“First do no harm.” The physician’s creed. This business about doing this in the right is, frankly, the part that gives me the most bother. I think I’m doing it responsibly and I think I’m doing it well enough, making sure folks understand that when they grab my extension, they aren’t getting something officially endorsed by StumbleUpon and so on. And the code is there. Granted, just because I can doesn’t imply that I should. But then just because I could screw up doesn’t mean that I will either. I expect this is also something that has to be considered on a case by case basis too. Apple actively checks for private API usage for any apps entering the App Store. SU doesn’t have that option, but I’ve also posted in their forums about this, so other than sending emails directly to their dev team, I’m not sure what else I could do. I suppose if they want me to stop, they can just send me an email. Until then, I think I’ll try to make use of what they’ve provided, albeit inadvertently. But I’m going to try to place nice while doing it.