Don't Build APIs
ceklog.kindel.com
Don't Build APIs
1–10 of 58 posts
Re: Don't Build APIs
#2Upvoted because I find it interesting, not because I agree with it.
FreshBooks has a very significant 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: http://community.freshbooks.com/addons/?header_addons=1 and they clearly built an app AND an API.
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 intelligently.
Re: Don't Build APIs
#3At 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.
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.
Yes, people will still complain. It's OK though if you provide a reasonable balance.
Re: Don't Build APIs
#4This 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.
One quick example:
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.
Absolute carnage. Tons of applications broke. This particular case was being used everywhere. 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.
In the end, we made the asynchronous functions silently fall back to synchronous memcpys in all cases when the stricter parameter validation failed.
Re: Don't Build APIs
#5Netsuite has a different url for each new version of their API (and they keep the old one live as well).
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.
Re: Don't Build APIs
#6At 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. 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 acc…
Myth? MS built a very successful business on it.
You know what happens when you get kill dates? One day all of a sudden half the web will stop working. There's a reason why people start back flipping to support out of date calls.
Customers don't care why your software just broke or whose fault it was, all they care about is it broke.
Re: Don't Build APIs
#7At 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. 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 acc…
Myth? MS built a very successful business on it. You know what happens when you get kill dates? One day all of a sudden half the web will stop working. There's a reason why people start back flipping to support out of date calls. Customers don't care why your software just broke or whose fault it was, all they care about is it broke.
> Myth? MS built a very successful business on it.
It's also an unsustainable business. How long do you think MS will be able to maintain backward full compatibility? 100 years? 200 years?
> Customers don't care why your software just broke or whose fault it was, all they care about is it broke.
Customers aren't engineers; they don't know better. We do. In any, it's going to be cheaper to abandon the stubborn customers than it will be to maintain decades worth of backward compatibility, at some point.
Re: Don't Build APIs
#8At 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. 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 acc…
Myth? MS built a very successful business on it. You know what happens when you get kill dates? One day all of a sudden half the web will stop working. There's a reason why people start back flipping to support out of date calls. Customers don't care why your software just broke or whose fault it was, all they care about is it broke.
If you have your kill-date iterate rapidly enough, and advertise it well enough, people who build products on your API will keep up, or the competitors will and take their business.
Heck, if you want to be really hand-holdy about it, have an warnmesage attribute in your returns that mentions various issues, and start throwing deprication warnings some $time before the kill date as a reminder.
And the number of bugs and security holes coming directly out of backwards compatibility in MS products was a very big issue for a very long time. Lately they have been doing much less in terms of backwards compatibility (e.g. run in "compatibility mode"), probably as and outgrowth of this.
Re: Don't Build APIs
#9Earlier quoted context omitted.
Myth? MS built a very successful business on it. You know what happens when you get kill dates? One day all of a sudden half the web will stop working. There's a reason why people start back flipping to support out of date calls. Customers don't care why your software just broke or whose fault it was, all they care about is it broke.
If you have your kill-date iterate rapidly enough, and advertise it well enough, people who build products on your API will keep up, or the competitors will and take their business. Heck, if you want to be really hand-holdy about it, have an warnmesage attribute in your returns that mentions various issues, and start throwing deprication warnings some $time before the kill date as a reminder. And the number of bugs a…
I think sophacles is onto something here.
In my post I tried to make it clear that backwards compatibility is a challenge for successful APIs.
However, I guess if you don't want to make your APIs successful you can do all kinds of things that make them harder to use, like putting in draconian kill-dates, warnmessages, etc... Make sure your documentation is extra-long and wordy too while you're at it.
Because, sophacles, is right: if you don't have a successful API you don't have to worry about pissing customers off.
Re: Don't Build APIs
#10This 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. One quick example: In CUDA, you have to explicitly copy memory to and from the GPU. We have two basic kinds of memcpy functions--synchronous and asynchronous. A…
Well, if it helps any, I've found the CUDA API to be somewhat lacking in features, but more or less robust, and pretty logical to deal with as a developer. Keep up the good work.