Fog Creek Software
Discussion Board




API Design

I'm heading up the API design for my company's next gen software package and was wondering if anyone knows of some good resources that deal with designing an API.  Books or web resources would be great.  The specific language is not important as we will be supporting multiple langauges (C++, Java, Perl, and possibly others) so I'm just looking for the general guidelines.

We've done API design before, but we're taking a more structured approach to it this time and we're trying to get it right.

Thanks in advance for any help.

Matt Lee
Friday, September 20, 2002

Good article on API design

The API Developer's Primer
Java Developer's Journal
March 2002. Vol 7 Issue 3
http://www.javadevelopersjournal.com

Unfortunately, this may not be of much use as the digital archive is apparently available to subscribers only.

Will Glass-Husain
Friday, September 20, 2002

Fortunately, I'm a subscriber and have the issue here at my desk.  Thanks.

Matt Lee
Friday, September 20, 2002

I've always like Object Oriented Software Construction by Bertrand Meyer. The second edition however isn't as good as the first (although it is much much longer).

Jeff Kotula
Friday, September 20, 2002

There's a book especially for API design: http://www.amazon.com/exec/obidos/ASIN/0201498413/ .
It's by one of the guys that wrote the LCC compiler.

Troy King
Friday, September 20, 2002

Oh yeah, re-read the "Candy Machine Interfaces" section of "Writing Solid Code" too :)

Troy King
Friday, September 20, 2002

I think the "C Interfaces and Implementations" book is overrated. It's mostly just some example code that the author is trying to show off.

I think "Writing Solid Code" is especially helpful, though re-reading (my all time favorite) "Code Complete" never hurts! ;-)

Zwarm Monkey
Friday, September 20, 2002

"Effective Java" by Joshua Bloch has a very strong bias of API design. Well, it's written by the lead Sun architect and the author of Java Collections. And it's one of the best Java books so far.

Evgeny Goldin
Saturday, September 21, 2002

Zwarm, I couldn't agree more about "Code Complete".

Troy King
Saturday, September 21, 2002

Yoy may also find "Design Corner" of Bill Venners
helpful - http://www.artima.com/javadesign/index.html

I remember him writing a book "API Design with Java" (http://www.artima.com/apidesign/index.html) but now it doesn't seem to be available on-line ..

Evgeny Goldin
Saturday, September 21, 2002

Chapter 4 of Kernighan & Pike's "The Practice of Programming" has a good treatment of designing interfaces.

Jeff, I'm glad I'm glad some one else thinks the second edition of Meyer's book isn't as good as the first. At least I don't think it is - I've never managed to finish it.

Andrew Simmons
Sunday, September 22, 2002

With APIs you unfortunately follow that excellent piece of advice: Plan to write two, you'll have to throw one away anyway.

Once an API is released it becomes very difficult to alter it.  So leave as much "space" in the API as possible.  Implement the minimum subset so that you can add to the API later *after* you've learned what works.

IanRae
Monday, September 23, 2002

Correction: With APIs you unfortunately can't follow that excellent piece of advice

oh the irony!

IanRae
Monday, September 23, 2002

*  Recent Topics

*  Fog Creek Home