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!