What is good API design?

http://richardminerich.com/2012/08/what-is-good-api-design/

by mattdeboard • 14 years ago

28 7 14 years ago

djcjr• 14 years ago

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.

dromidas• 14 years ago

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

joeld42• 14 years ago

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

tmurray• 14 years ago

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.

Rickasaurus2• 14 years ago

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.

dreamdu5t• 14 years ago

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.

Rickasaurus2• 14 years ago

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

What is good API design?

Related Stories