OP here.<p>When I wrote this post, I didn't imagine so many people would react by saying, essentially<p>"Screw the customers. Just break 'em."<p>One of the reasons I have my panties in wad over this topic is the Web has made it far easier for people to create APIs that get used by others. Back in the olden-days you HAD to be Microsoft or similar to get the kind of traction a kid in his parent's basement can get with a little Python and a Heroku account.<p>But something else has changed along the way: Composability.<p>Yes, I worked on COM, OLE, ActiveX and all that crap. I was thinking deep thoughts about composable software back in the stone ages (and even then, it had all already been done by others smarter than I in the 70s & 80s).<p>But today it is REAL. The Web technology stack has actually, finally, enabled massive distributed systems composed of loosely coupled components from multiple independent parties! The dream of my computing youth has become reality!<p>These things are connected by APIs.<p>(Which, by the way are not just function calls. A API can be a REST end-point, a file format, or a database schema, amongst other things).<p>Yes, you as an API provider can choose to deprecate your API anytime you want. Use kill-dates, warnmessages, etc... You can even create new, independent & parallel versions. It will help.<p>But you will find that someone else has built something that uses your API, that exposes its OWN API and now there's a 3rd party indirectly dependent on you. Be prepared for it.<p>APIs are actually easy to build. That is the problem. The solution is to realize that statement is actually false.
This post is very accurate. I build APIs for a living (CUDA), and this lines up pretty well with my experience. Writing APIs is very tough, you will get a lot of things wrong, and the fixes available to you after you realize your mistake are all ugly at best.<p>One quick example:<p>In CUDA, you have to explicitly copy memory to and from the GPU. We have two basic kinds of memcpy functions--synchronous and asynchronous. Asynchronous requires some additional parameter validation because the GPU has to be able to DMA that particular piece of memory, etc. After we had been shipping this for a release or two, we noticed that our parameter checking for the asynchronous call was missing one very particular corner case and would silently fall back to synchronous copies instead of returning an error. We thought, okay, let's just fix that by returning an error because surely no one managed to hit this.<p>Absolute carnage. Tons of applications broke. This particular case was being used <i>everywhere</i>. It provided no benefit whatsoever in terms of speed; in fact, it was just a more verbose way to write a standard synchronous memcpy. People did it anyway because... they thought it must be faster because it had async in the name? I don't know.<p>In the end, we made the asynchronous functions silently fall back to synchronous memcpys in all cases when the stricter parameter validation failed.
At some point, we need to kill the myth of backwards compatible. This has caused more problems than it fixes. Further, at this point in history, app updates are trivial and built into everything, so retaining backwards compatibility is not so much of a necessity.<p>When designing APIs, use versions and have a kill date in place. Even if you don't change the API, release the same one under a new version number. Kill access to the old version on the kill date. Keep N versions accessible at a time, to reduce the burden on app writers, but don't slack on the kill date. This will give you a timeline and procedure to avoid hacking in crazy backwards compatibility, and targets for total rewrites.<p>Yes, people will still complain. It's OK though if you provide a reasonable balance.
The key problem here is that "backwards compatibility" means "backwards compatibility for people abusing the API in undocumented ways".<p>Don't do that. That way lays insanity. Be very, very clear up front that you <i>will</i> break backwards compatibility for those folks. Don't sweep it under the table, be very vocal about having done it. There will be short term pain as important customers (eg Adobe) learn the hard way that you really mean it. And long term relief as you don't have that legacy headache growing so quickly.<p>One estimate is that a 25% increase in requirements results in a 100% increase in software complexity. (See <i>Facts and Fallacies of Software Engineering</i> for a source.) That means that the complexity grows as the number of requirements cubed. Therefore the key to a good API is that it be short and simple. When you start to add implicit requirements on top of explicit ones, it quickly becomes long and complex, and the necessary software to support it and make future modifications becomes much worse.<p>This does not mean that designing APIs is not hard. But don't let your API become what is published and quirks that are not. Just don't.
Upvoted because I find it interesting, not because I agree with it.<p>FreshBooks has a very <i>significant</i> amount of their usage/profit from their API. These are just their endorsed/vetted add-ons, let alone all the ones out there in the wild: <a href="http://community.freshbooks.com/addons/?header_addons=1" rel="nofollow">http://community.freshbooks.com/addons/?header_addons=1</a> and they clearly built an app AND an API.<p>The API for FreshBooks was a major portion of their (very successful) strategy, so I can't see why people can't do both, provided they do it <i>intelligently</i>.
This post addresses many of the issues we've dealt with at RadioReference.com. We version our primary APIs which has worked very well, but occasionally we have to abstract and write translations for backwards compatibility. We also need at times to deprecate versions and features.<p>But, this quote in the post is important: "<i>When exposing APIs be absolutely certain the value you get from doing so is worth it.</i>"<p>In our case, our APIs are a significant revenue driver and are worth it. Don't let OP discourage you from exposing your platform's data via APIs. Instead, let this post warn you what to look out for when exposing APIs.
This boils down to a simple question:<p>Are most of your API users ahead of you, or behind you?<p>If you have an immature API with a smallish number of users, and you think that incompatible changes in the API will improve adoption with the vast bulk of your (not-yet-on-board) potential market, then go ahead, break the API.<p>If the only reason people use your API is because of its legacy -- if you think that by changing your API people will wake up from their inertial slumber and investiate your superior competitors, then don't break your API under any circumstances.<p>Obviously there are grey points in between, and a series of small breaking changes will be worse than occasional large breaking changes. But by and large, the success of your platform will depend on its utility, not legacy compatibility. This is why stripe and wepay will eventually conquer paypal, why python will continue to be a vibrant community, why java will eventually fade to cobol-like obscurity, and why Microsoft Windows is fundamentally doomed. It's hard to look backwards and forwards at the same time.
This reminds me of a Joel Spolsky post from years ago:<p><a href="http://www.joelonsoftware.com/articles/APIWar.html" rel="nofollow">http://www.joelonsoftware.com/articles/APIWar.html</a><p>Essentially, Microsoft shoots itself in the foot by trying to stay extremely backwards compatible, even to the detriment of making their products better.
Public APIs are forever – you get one chance to get it right. Unless nobody's heard of your API and thus nobody uses it, in which case you're safe, but also screwed.
Build the best API you know how to build and ask questions later. If your business is doing well, then supporting your API forever is a high quality problem.
My biggest issue with web APIs is the speed at which they change means you often get a lack of maintenance of documentation. The speed of change compounds the effects, the discussions you find on the API usage only months old have lost relevance in non obvious ways.<p>Facebook and Paypal are or have been guilty of this in the past though Facebook is a lot better than it was.
Netsuite has a different url for each new version of their API (and they keep the old one live as well).<p>This was great for me because my code never broke, which was important because It was running the back-end of an e-commerce site. It gave me more than enough time to upgrade when I wanted bug fixes/features.