Ask HN: Best books in API design
What books do you recommend on the subject?
11 comments
Anything by Josh Bloch
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!
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!
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].
Where is the video available?
It's the first result on google:
http://www.youtube.com/watch?v=aAb7hSCtvGw
http://www.youtube.com/watch?v=aAb7hSCtvGw
second (foo, I'm just not fast enough to post much around here ;-)
Not a book, but Trolltech (makers of Qt) has nice recommendations for API design:
http://doc.trolltech.com/qq/qq13-apis.html
http://doc.trolltech.com/qq/qq13-apis.html
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
That's an excellent resource - I particularly like how they use examples from early versions of their own APIs of what not to do.
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.
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.
dummy comment - sorry guys, i'm trying this out
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
http://wiki.apidesign.org/wiki/Main_Page http://www.amazon.com/gp/product/1430209739
If you are interested in REST API's, the best I've ever read is "RESTful Web Services" by Richardson & Ruby.
SICP
Interface Oriented Design by Ken Pugh is pretty good (http://pragprog.com/titles/kpiod/interface-oriented-design)
What about: Service-Oriented Design with Ruby on Rails?
Any comments?
http://www.amazon.com/Service-Oriented-Design-Ruby-Rails-Pau...
Any comments?
http://www.amazon.com/Service-Oriented-Design-Ruby-Rails-Pau...
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.