9 ms·

The Little Manual of API Design (2008) [pdf]

142 points by daviducolo 11y ago

holgerp 11y ago
some good advice, some doubtful advice. One advice in this pdf is that on designing first before implementing. I think iterative cycles of design / implement / use / design /implement use yield better results.
- jalfresi 11y ago
  Iterative cycles take advantage of the regularity of change. APIs shouldn't change once public, hence the emphasis on Big Upfront Design. However, change still needs to happen so versioning comes into play. Personally, when it comes to APIs, you can tell those that have been designed upfront rather than iteratively; they are generally better IMHO.
  - seanmcdirmid 11y ago
    The API that appears to be well-designed up front was probably preceded by many not as great APIs either done by the same designers, or that could at least be learnt from. That is still quite iterative, just in the long term sense. Real waterfalls don't exist. If you have an API that does something well known, find and learn from existing APIs that do that. If not, then he prepared for lots of trial and error, scenarios you didn't think of, and so on. It might make sense to put out a "worse is better" API first so the learning and feedback loops can start.
- talles 11y ago
  What I would advice is to design the API (public part) without considering the internal code (private part). We often change our point of view on how to solve a problem (private part), but rarely the problem itself changes (public part). Iterate away your (internal) architecture as much as you want, but when dealing with the API (your external world interface) make sure to put yourself in your user shoes.
darylteo 11y ago
Seen some of these around... what I've been craving for is a little pdf of web api design.
fizixer 11y ago
I've been thinking about this at a meta level and I can't get to reach any conclusion. Think of a simple instruction: draw a line from (a,b) to (c,d). How many ways can it be "encoded as an API"? we already have a gazillion forms of drawing: SVG, OpenGL, Postscript, Asymptote, PGF/Tikz, Canvas, and so on. Why? Forget about existing line-drawing APIs. Which of these would you choose? - line(a,b,c,d) - Line (a,b) to (c,d) - draw-line (a,b) (c,d) - drawline - make-a-line - line-from-to - ... - ... Not to mention placement of parentheses (C vs s-expression), curly braces or angle bracket. The list goes on. I started reading Bertrand Russell's 'On Denoting' but I'm not really sure it'll help me out (although I haven't finished reading it yet). At another level: once you've converted your vector graphics primitive to "pixel maps", that itself is no less of a language. So at a more fundamental level, it's really information represenation, not language. I'm not sure where the problem is, language vs computable-form vs information-representation. Not to mention metalinguistics. Because API is not just one layer on top of your program. You build an API/language layer as a scaffolding, to use it to build a higher level API/language layer. And apparently its turtles all the way up and all the way down. It's all very confusing
- arsey 11y ago
  When thinking about the API only, any one of your line implementations seems just as good as the other. But if you also ask "which of these makes sense for the client application" that will likely narrow your options down. Indeed, the parent PDF says that before even writing any code, write use cases. "The implementation should adapt to the user, not the other way around."
- areop 11y ago
  The right answer for a API to draw a line like you describe is to provide every possible way to draw a line since you never know which one the user wants to use. Granularity is one of the general five properties of every good API, of course it is not always good to provide all possible ways since it hurts compactness. The best I have ever heared about API design was a talk from Casey Muratori: http://mollyrocket.com/casey/stream_0028.html http://mollyrocket.com/casey/stream_0028.html
  - 11y ago
to3m 11y ago
Related to section 3.7: you should try to create as much builtin functionality as possible (ideally, all of it...) using the mechanism(s) provided for 3rd party extensions. This can give everybody confidence that the extension mechanism is useful and complete; if library source code is provided, it also provides a good stock of example extensions.
trumpete 11y ago
> Because HTML forces us to repeat the name of the tag in the close tag, it encourages us to write things like: the goto label statement What sort of demonic possession bullshit going on here? Who is "encouraged" to do such thing?
- blowski 11y ago
 I guess the OP means something more like "HTML makes it easy to make mistakes like ..." which is true. I believe English is not his native language.
 - scott_s 11y ago
 I think that is what the author means, but I also think it's a valid usage; it's ironic.
- bencoder 11y ago
 You are, presumably, already a developer, so you already understand nesting. Perhaps a better example that a beginner could find quite reasonable after learning about start and end tags: Underlined. Bold and underlined. Bold only. Why shouldn't that work?
 - smashface 11y ago
 This is a much better example of the point the author was trying to illustrate. Though I'm not sure sure if the HTML / TeX comparison is the best to exemplify the concept. I feel that if a beginner were to make the conceptual mistake that HTML tags are not nested that they may also not grasp that {}'s are to be nested as well. Thus falling into the same trap as HTML. I'll admit that {}'s look more obvious to form a nested structure but it may also be that my eyes are trained to see them exactly as such.
 - arnsholt 11y ago
 That's not allowed because parsing that kind of nesting requires a context sensitive parser, which is much more expensive computationally than context free parsers.
omgitstom 11y ago
Something that I've found extremely valuable with API design for public facing APIs is use readme driven development. I think it complements a lot of the points brought up in the PDF .

142 points by daviducolo 11y ago

some good advice, some doubtful advice. One advice in this pdf is that on designing first before implementing. I think iterative cycles of design / implement / use / design /implement use yield better results.

jalfresi 11y ago
Iterative cycles take advantage of the regularity of change. APIs shouldn't change once public, hence the emphasis on Big Upfront Design. However, change still needs to happen so versioning comes into play. Personally, when it comes to APIs, you can tell those that have been designed upfront rather than iteratively; they are generally better IMHO.
- seanmcdirmid 11y ago
  The API that appears to be well-designed up front was probably preceded by many not as great APIs either done by the same designers, or that could at least be learnt from. That is still quite iterative, just in the long term sense. Real waterfalls don't exist. If you have an API that does something well known, find and learn from existing APIs that do that. If not, then he prepared for lots of trial and error, scenarios you didn't think of, and so on. It might make sense to put out a "worse is better" API first so the learning and feedback loops can start.
talles 11y ago
What I would advice is to design the API (public part) without considering the internal code (private part). We often change our point of view on how to solve a problem (private part), but rarely the problem itself changes (public part). Iterate away your (internal) architecture as much as you want, but when dealing with the API (your external world interface) make sure to put yourself in your user shoes.

darylteo 11y ago

Seen some of these around... what I've been craving for is a little pdf of web api design.

fizixer 11y ago

I've been thinking about this at a meta level and I can't get to reach any conclusion. Think of a simple instruction: draw a line from (a,b) to (c,d). How many ways can it be "encoded as an API"? we already have a gazillion forms of drawing: SVG, OpenGL, Postscript, Asymptote, PGF/Tikz, Canvas, and so on. Why? Forget about existing line-drawing APIs. Which of these would you choose? - line(a,b,c,d) - Line (a,b) to (c,d) - draw-line (a,b) (c,d) - drawline - make-a-line - line-from-to - ... - ... Not to mention placement of parentheses (C vs s-expression), curly braces or angle bracket. The list goes on. I started reading Bertrand Russell's 'On Denoting' but I'm not really sure it'll help me out (although I haven't finished reading it yet). At another level: once you've converted your vector graphics primitive to "pixel maps", that itself is no less of a language. So at a more fundamental level, it's really information represenation, not language. I'm not sure where the problem is, language vs computable-form vs information-representation. Not to mention metalinguistics. Because API is not just one layer on top of your program. You build an API/language layer as a scaffolding, to use it to build a higher level API/language layer. And apparently its turtles all the way up and all the way down. It's all very confusing

arsey 11y ago
When thinking about the API only, any one of your line implementations seems just as good as the other. But if you also ask "which of these makes sense for the client application" that will likely narrow your options down. Indeed, the parent PDF says that before even writing any code, write use cases. "The implementation should adapt to the user, not the other way around."
areop 11y ago
The right answer for a API to draw a line like you describe is to provide every possible way to draw a line since you never know which one the user wants to use. Granularity is one of the general five properties of every good API, of course it is not always good to provide all possible ways since it hurts compactness. The best I have ever heared about API design was a talk from Casey Muratori: http://mollyrocket.com/casey/stream_0028.html http://mollyrocket.com/casey/stream_0028.html
- 11y ago

to3m 11y ago

Related to section 3.7: you should try to create as much builtin functionality as possible (ideally, all of it...) using the mechanism(s) provided for 3rd party extensions. This can give everybody confidence that the extension mechanism is useful and complete; if library source code is provided, it also provides a good stock of example extensions.

trumpete 11y ago

> Because HTML forces us to repeat the name of the tag in the close tag, it encourages us to write things like: the goto label statement What sort of demonic possession bullshit going on here? Who is "encouraged" to do such thing?

blowski 11y ago
I guess the OP means something more like "HTML makes it easy to make mistakes like ..." which is true. I believe English is not his native language.
- scott_s 11y ago
  I think that is what the author means, but I also think it's a valid usage; it's ironic.
bencoder 11y ago
You are, presumably, already a developer, so you already understand nesting. Perhaps a better example that a beginner could find quite reasonable after learning about start and end tags: Underlined. Bold and underlined. Bold only. Why shouldn't that work?
- smashface 11y ago
 This is a much better example of the point the author was trying to illustrate. Though I'm not sure sure if the HTML / TeX comparison is the best to exemplify the concept. I feel that if a beginner were to make the conceptual mistake that HTML tags are not nested that they may also not grasp that {}'s are to be nested as well. Thus falling into the same trap as HTML. I'll admit that {}'s look more obvious to form a nested structure but it may also be that my eyes are trained to see them exactly as such.
- arnsholt 11y ago
 That's not allowed because parsing that kind of nesting requires a context sensitive parser, which is much more expensive computationally than context free parsers.

omgitstom 11y ago

Something that I've found extremely valuable with API design for public facing APIs is use readme driven development. I think it complements a lot of the points brought up in the PDF .