
The Little Manual of API Design (2008) [pdf] - daviducolo
http://www4.in.tum.de/~blanchet/api-design.pdf
======
fizixer
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

~~~
EliRivers
Apropos of nothing much, back when I was coding primarily in Objective-C
(incidentally, for cross-platform Linux and Windows, but not anything Apple)
the form of the function call would give another much more expressive option.
I'd write something like this:

    
    
      [drawline  from: A
                   to: B];
    

Obviously, some people hate it.

~~~
JoshTriplett
Objective-C syntax aside, keyword arguments are great for readability and
maintainability.

------
trumpete
> Because HTML forces us to repeat the name of the tag in the close tag, it
> encourages us to write things like:
    
    
       the <b>goto <u>label</b></u> statement
    

What sort of demonic possession bullshit going on here? Who is "encouraged" to
do such thing?

~~~
bencoder
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:

    
    
       <u>Underlined. <b>Bold and underlined.</u> Bold only.</b>
    

Why shouldn't that work?

~~~
arnsholt
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.

~~~
tricolon
I understand that, you understand that, and your parent commenter probably
understands that, but the point is that a user of HTML should not have to
understand it.

~~~
Arnavion
IRC formatting codes (not standard, but popularized by mIRC and thus
implemented by most clients) are also toggles instead of begin-end pairs, so
they allow this. If I remember correctly, old text processors like WordStar
also implemented formatting as toggles.

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

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

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

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

