4 ms·

API designers should be writers

19 points by davewiner 15y ago

mattdeboard 15y ago
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.
spacemanaki 15y ago
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.

19 points by davewiner 15y ago

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.

spacemanaki 15y ago

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.