Tuesday, February 25, 2014

How to design a good API?

How to design a good API?

API design is incredibly hard, you'll get it wrong. The only way to make a good API is to take someone else's API, figure out why it sucks and then to try to fix that while copying every single other aspect that does not suck. So whenever you design an API you need to be able to answer the question for every element of it: Where did I "steal" this from and why is it not the same as the original?
And one of the best sources to steal from is yourself. I've been rebuilding the same framework roughly every 2 years since 2005 (possibly before but that becomes more paleontology) and it seems to be getting quite good by now; I'll still make a new one in a couple of years.
Because one will fail to design the perfect API, the only professional thing to do is to anticipate failure and plan accordingly. It is hard to say what that means: To me is currently means that for every API to build a less abstract/declarative/opinionated building block which can be easily assembled to form the API that I want, but which, if the API turns out to suck (which it will) can be reassembled to do something else.

Mr. Steve Jobs (see video) suggests to steal ideas in the general case of design – and APIs aren't even copyrightable (Right? Oracle? Right!), which was a wise decision by the forefathers of our laws to let us iterate on API design. So, does "stealing" an API mean to literally copy it? There is a good argument for that as it decreases entropy in the API universe making them easier to learn for your customers – but, I think, it should be OK to add a little artist touch to some of the things :)
http://www.youtube.com/watch?v=CW0DUg63lqU