Ask HN: Best books in API design

https://news.ycombinator.com/item?id=1668561

by grep • 16 years ago

36 17 16 years ago

news.ycombinator.com

What books do you recommend on the subject?

devmonk• 16 years ago

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!

jefffoster• 16 years ago

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

sammyo• 16 years ago

second (foo, I'm just not fast enough to post much around here ;-)

jon_hendry• 16 years ago

Where is the video available?

kroger• 16 years ago

It's the first result on google:

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

bd• 16 years ago

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

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

arethuza• 16 years ago

That's an excellent resource - I particularly like how they use examples from early versions of their own APIs of what not to do.

icefox• 16 years ago

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

silentbicycle• 16 years ago

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• 16 years ago

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

locopati• 16 years ago

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

garnaat• 16 years ago

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

c00p3r• 16 years ago

SICP

indy• 16 years ago

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

grep• 16 years ago

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

Any comments?

http://www.amazon.com/Service-Oriented-Design-Ruby-Rails-Pau...

ewanmcteagle• 16 years ago

Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries (2nd Edition) http://www.amazon.com/Framework-Design-Guidelines-Convention... 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.

nl• 16 years ago

Anything by Josh Bloch

Ask HN: Best books in API design

Related Stories