A good way to ensure that complexity is encapsulated is to have a priority of constituencies. This is what it looks like for the web platform: it says end users are above web developers, who are above browser developers, who are above spec writers, and all of these are above theoretical purity. As someone designing APIs for the web platform, this means your needs as authors are above my needs as a spec writer. The groups will obviously be different in your own case, but the main idea is still the same: prioritize users over implementers at every level, and prioritize every human over theoretical purity.