
API designers should be writers - davewiner
http://scripting.com/stories/2011/06/21/apiDesignersShouldBeWriter.html
======
spacemanaki
I don't remember where (maybe Coders At Work?) but I've read recommendations
that API design be thought of as a language design. I certainly believe that
thinking about programming language design would help refine the same "taste"
that would result in high quality APIs. For instance, the kind of
thoughtfulness that Christian Queinnec talks about in Lisp in Small Pieces,
talking about type conversion functions like string->number,

    
    
        "Personally, I don't like names formed like this x->y to indicate a
        conversion because this order makes it difficult to understand
        compositions: for example, (y->z (x->y ... )) is less straightforward
        than (z<-y (y<-x ...)). In contrast x->y is much easier to read than
        y<-x. You can see here one of the many difficulties that language
        designers come up against." (footnote on p 5)
    

Also, I think it was in Coders At Work that Joshua Bloch said that APIs should
be carefully designed because it's hard to change them, and also designed with
public consumption in mind, because by the time your private, in-house API is
made public, you can't change it. I think he mentions this repeatedly in
Effective Java too.

My painful experience developing for the BlackBerry OS has really brought this
point home to me, I think many parts of that API were not thought through, and
were never meant to be public.

------
mattdeboard
I can't say as though I share the OP's sentiment wrt the Amazon API, or at
least the boto Python bindings. It's a bit silly that I have to fetch all my
instances (or, at best, all instances in a region, but all ours are in a
single region) to operate on a single one. Other than that though, what
functionality I've used in boto has been straightforward.

Also I kind of lost the thread on what this blog post was about. I'd have
liked to see firmer examples of economy of words/commands in API construction,
as I'm working on an API myself right now.

