API design, part 2

When faced with the task of designing APIs for a problem that has a lot
of inherent complexity, an essential first step is to design exactly
how and where to hide that complexity. I was recently faced
with the need to redesign an API that I'd created before I learnt this
lesson, and I think I did a good job of it - the complexity is almost
entirely hidden from users on both "producer" and "consumer" sides of
the API.

However, in the process I've learnt another essential, if (in
retrospect) obvious lesson: Just because you've figured out how to hide
the complexity doesn't make the complexity go away. Implementing the
code that actually does the hiding is still complex, probably
even more so due to the need to provide the illusion of simplicity.
Forget this at your peril!