Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Ask HN: Best books in API design

news.ycombinator.com

Post reply on HN
Print view View original

1–10 of 18 posts

Re: Ask HN: Best books in API design

#2

Post by 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!

Re: Ask HN: Best books in API design

#5

Post by 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.

Re: Ask HN: Best books in API design

#8

Post by sammyo »

jefffoster wrote: post #3

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

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