Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Don't Build APIs

ceklog.kindel.com

Post reply on HN
Print view View original

11–20 of 58 posts

Re: Don't Build APIs

#11

Post by ajross »

dlitz wrote: post #7
mattmanser wrote: post #6

Earlier 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.

> 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 custome…

100 years sounds reasonable. Old APIs simply get frozen and new ones take their place. Apps written to .NET, for example, aren't bound by compatibility concerns with the early win32 GDI implementations. Cocoa apps aren't impacted by Carbon's compatibility concerns.

What's the option? Throw whole platforms out and start over every 15 years? Does that scale? It has so far only because the industry has been growing (more smartphones than PCs, more PCs than workstations, more workstations than minicomputers, etc...). But it won't grow forever.

Re: Don't Build APIs

#12

Post by sophacles »

cek wrote: post #9
sophacles wrote: post #8

Earlier quoted context omitted.

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, sophacl…

This is a false dilemma. Just because you set up some opposing conditions: backwards compatibility or unsuccessful api doesn't actually make it true. Just an assertion.

Having a reasonable end of life on support never hurt apple. There are lots of things that I can no longer run on the latest version of OSX. This happens every time the OS upgrades. Except of course they don't use versioned APIs, so it is much less planned for and not really as easy to deal with for devs.

I'm not saying make a shitty API, I'm saying, if you have the people who depend on your product know that changes happen, they can prepare for it. If you release a new version of the API every 6 months, and only support them for 18 months, you can make the api migrate slowly enough that it isn't a serious change for each version.

In native code: anything compiled to old APIs can link to old versions of your library, and just work the same way. In web apis: the world changes faster than the 18 month thing anyway, so whatever.

If people want to depend on your bugs, you told them not to, they can deal with the changes.

Re: Don't Build APIs

#13

Post by ageektrapped »

paulhauggis wrote: post #5

Netsuite 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.

Yes! This wasn't what the OP was referring to, though: he had shipping shrink wrap software with APIs in mind. But still, you're totally right and this occurred to me as I was reading the post, for Web APIs: keep versioning the URL for every shipped revision of your API. You'll have to document like crazy, of course. You can even detect stragglers on old versions and help them get on the new version.

Re: Don't Build APIs

#14

Post by btilly »

The key problem here is that "backwards compatibility" means "backwards compatibility for people abusing the API in undocumented ways".

Don't do that. That way lays insanity. Be very, very clear up front that you will 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.

One estimate is that a 25% increase in requirements results in a 100% increase in software complexity. (See Facts and Fallacies of Software Engineering 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.

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.

Re: Don't Build APIs

#15

Post by georgemcbay »

mattmanser wrote: post #6
sophacles wrote: post #3

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. 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.

I'm actually quite fond of the way Microsoft historically bent over backwards for backward compatibility, but OTOH Facebook is also very successful and has a very successful ecosystem of third-party users of their APIs. Facebook is like the anti-Microsoft in that they randomly change and break their APIs at such an alarming rate that you have to wonder if they are intentionally fucking with you if you code against their APIs.

Obviously the needs for a web API and the needs for an API with a specific binary ABI on a local OS are quite different but I think for either environment, most API developers can comfortably fit somewhere between those two extremes where they don't continue to support inherently unsupported API usage, but they don't break something randomly every week.

Re: Don't Build APIs

#16

Post by blantonl »

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.

But, this quote in the post is important: "When exposing APIs be absolutely certain the value you get from doing so is worth it."

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.

Re: Don't Build APIs

#17

Post by hartror »

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.

Facebook and Paypal are or have been guilty of this in the past though Facebook is a lot better than it was.

Re: Don't Build APIs

#18

Post by cek »

btilly wrote: post #14

The key problem here is that "backwards compatibility" means "backwards compatibility for people abusing the API in undocumented ways". Don't do that. That way lays insanity. Be very, very clear up front that you will 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…

OP here.

I think this is very naive/utopian.

Yes, be super focused in your design.

Yes, only expose APIs you have clear use cases for.

Yes, keep the surface area as small as possible.

Yes, have very focused requirements.

Yes, document the hell out of things.

Yes, implement strong parameter validation and other things to try to reduce the chance people do bad things.

Do all these things and more (these are all part of what makes exposing APIs hard work, that many people don't do).

But do not, for one second, believe that someone still won't do it wrong or abuse your perfectly designed API eventually... especially if it is successful.

Re: Don't Build APIs

#19

Post by btilly »

cek wrote: post #18
btilly wrote: post #14

The key problem here is that "backwards compatibility" means "backwards compatibility for people abusing the API in undocumented ways". Don't do that. That way lays insanity. Be very, very clear up front that you will 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…

OP here. I think this is very naive/utopian. Yes, be super focused in your design. Yes, only expose APIs you have clear use cases for. Yes, keep the surface area as small as possible. Yes, have very focused requirements. Yes, document the hell out of things. Yes, implement strong parameter validation and other things to try to reduce the chance people do bad things. Do all these things and more (these are all part of…

I agree with all of what you just said. But I think that the post is not a good demonstration of that.

Microsoft failed at keeping the surface area as small as possible. When their surface area expanded to a hack to deal with Adobe's hack of replacing code behind Microsoft's back, they went into very dangerous territory.

Re: Don't Build APIs

#20

Post by blantonl »

sophacles wrote: post #3

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. 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 of backwards compatible"

What is the "myth" of backward compatible?

I wholeheartedly agree with your second paragraph regarding versions and kill dates - but every API is different. In our case, when our API changes/versions/deprecates - WE are directly held responsible by customers of consumers of the API - since API consumers trumpet the fact that they have integrated with our API.

On the surface, versioning and kill dates are great end-all solutions, but the reality is API consumers have a ton of leverage when your API is successful at generating revenue for you. Especially when those consumers are sending lots of revenue your way from their own customers, which think you are the source.

Post reply on HN