
What is good API design? - mattdeboard
http://richardminerich.com/2012/08/what-is-good-api-design/
======
tmurray
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.

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

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

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

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

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

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

