
Ask HN: Best books in API design - grep
What books do you recommend on the subject?
======
silentbicycle
While it's ostensibly about C, David Hanson's _C Interfaces and
Implementations_ (<http://sites.google.com/site/cinterfacesimplementations/>)
has a lot of good discussion about API design for libraries, how to handle
errors gracefully, etc. Many points apply just as well to libraries in OO or
functional languages, REST APIs, etc., because questions about who should be
responsible for error checking, managing resources, etc., are going to come up
in any API design.

It's also a good example of literate programming, and one of the best C books
I've read.

I'd also recommend _against_ _Design Patterns_, because while some of the API
design discussion is good, much of it is too entangled with workarounds for
quirks in C++'s object system. Visitor is irrelevant if you have multimethods,
Singleton is a non-issue if you have a prototype-based object system, etc.,
but this isn't clear. C's lack of a specific object system makes the focus on
API design clearer in CII.

~~~
test4service
dummy comment - sorry guys, i'm trying this out

------
jefffoster
There's a good video available "How To Design A Good API and Why it Matters"
by Josh Bloch. There's a selection of slides to accompany a version of the
talk here <http://lcsd05.cs.tamu.edu/slides/keynote.pdf> [PDF].

~~~
jon_hendry
Where is the video available?

~~~
kroger
It's the first result on google:

<http://www.youtube.com/watch?v=aAb7hSCtvGw>

------
bd
Not a book, but Trolltech (makers of Qt) has nice recommendations for API
design:

<http://doc.trolltech.com/qq/qq13-apis.html>

~~~
icefox
A few years after that article came out Jasmine (from Trolltech) and several
other devs put together a fantastic free pdf/book that I highly recommended.
"The Little Manual of API Design": <http://chaos.troll.no/~shausman/api-
design/api-design.pdf>

------
devmonk
Good API design is such a broad topic (because there are a wealth of
programming languages and ways you can communicate with systems and code) that
you're not going to find one that probably suits you without being more
specific.

Lets assume you are talking about a class API (like a C, C++, Java API for
example) and are just either defining a library or an interface into your
application from code that is loaded from the application's runtime
environment. In that case I could say what you might look into first would be
good OO design and head you off into "Design Patterns" as a classic (there is
also an online Java equivalent of that book which I think is "Java Design
Patterns"). But then you'll spend your years as a junior and mid-tier
developer obsessed with designs and which design to best use. Having the right
classes that "make sense" to a developer is wise, but spending too much time
with patterns isn't.

What I'd suggest is to just look at a number of APIs similar to what you want
and try to create something similar. Basically you want something intuitive,
so design something similar to what developers are used to. Consider what
needs to be public in the API. If it isn't providing something obviously and
directly related, it should be in a different library. As for deprecation of
methods over time, this used to be something that was done differently than
now. Used to be that you would be concerned about people continuing to use
your API with older code. These days a number of groups developing (especially
for applications) will force people to change and update by making their API
less backwards compatible (not many do this, but enough to make it hurt- and
it sucks). Good luck!

------
garnaat
If you are interested in REST API's, the best I've ever read is "RESTful Web
Services" by Richardson & Ruby.

------
ewanmcteagle
Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable
.NET Libraries (2nd Edition) [http://www.amazon.com/Framework-Design-
Guidelines-Convention...](http://www.amazon.com/Framework-Design-Guidelines-
Conventions-Libraries/dp/0321545613/) is an interesting read and contains the
result of actual work on building a large and successful framework. Has
information on exceptions, naming, extensibility, and common patterns.

------
locopati
Haven't read the book (it's on my long list), but the author has a decent blog
riffing on API design ideas

<http://wiki.apidesign.org/wiki/Main_Page>
<http://www.amazon.com/gp/product/1430209739>

------
grep
What about: Service-Oriented Design with Ruby on Rails?

Any comments?

[http://www.amazon.com/Service-Oriented-Design-Ruby-Rails-
Pau...](http://www.amazon.com/Service-Oriented-Design-Ruby-Rails-
Paul/dp/0321659368/ref=sr_1_fkmr0_2?ie=UTF8&qid=1283868123&sr=8-2-fkmr0)

------
indy
Interface Oriented Design by Ken Pugh is pretty good
(<http://pragprog.com/titles/kpiod/interface-oriented-design>)

------
nl
Anything by Josh Bloch

------
c00p3r
SICP

