What is good API design? | Hacker News Reader

What is good API design?

richardminerich.com

28 pointsmattdeboard7 comments

The hardest part about API design is picking the appropriate primitives in the first place. Use cases are relatively easy--somebody has a problem, come up with a solution--but any solution can be expressed in a myriad of different ways. The way that the API designer expresses that solution to the users of the API will impact the way code is written.

Users generally won't understand the implementation of the API, so instead they build a model of how they think the entire system operates. In the process, they make assumptions about performance, side effects, etc. that may be totally incorrect. Good APIs anticipate these assumptions and make them relatively easy to predict with some level of experience, either from elsewhere in the API or from similar APIs.

I'd say that this is also where good documentation comes into play. Anyone who is going to be spending a lot of time with your API should be able to fully trust it and eventually have a strong understanding of how the system works by simply looking up things in the documentation.

If you're selling an API though, it's even more important that most users can just drop it in and forget about it. This is how you maximize evaluation to purchase conversions. The implication of this is you need to spend a lot of time thinking hard about what defaults would be best for most users. Of course, you don't always get this right off the bat but the sales and support teams will let you know pretty quickly how it's going after the initial release of a new product.

Here's a fantastic presentation about API design: http://mollyrocket.com/873

IMO, an interpreter is the best way to interface between two systems, to which you feed a string or a file of your "language". This is the most flexible, and can even be separated into different versions, without ever breaking existing clients, so long as specifying the version is possible in your "language".

Thus, I think what makes API's so difficult is that they roughly approximate an interpreter, and in a particularly inflexible way.

The purpose of an API is to interface. Good API design means maximum interoperability. It should be consistent and transparent, while adhering to a published and open standard that facilitates interoperability.

What is that? A well-designed RESTful API that conforms to HTTP specs.

The other critical component that goes along with good API design is good API documentation.

Back before we had HTTP APIs we called the public facing parts of a library APIs too.

Don't forget the 0.001% which want to hack the crap out of your API and use it for exploitation :)

Reply on news.ycombinator.com