There's always a balance between giving an overview for people who have never done this sort of thing before and writing to the aficionados with the battle scars of having done this a few times. Happy to share more detailed notes here, but as it was the original post was quite long already.

I would very much agree with you - the difficulty in writing APIs well come from the fact that 1) it is challenging to predict how people will use it, so you have to code defensively, make sure it's accessible to beginners and sufficiently powerful for experts. 2) once you've published it, even small tweaks become highly painful, increasingly so as you see success.

Love the parallels with U.N. Peacekeeping