Isn't that the opposite of the lesson to learn? Design should be sending the correct outward signals and function the way users will expect. Users should not need to understand the inner workings.
Agree 100%, but good APIs aren't just a raw interface to a snapshot of how a system happens to be implemented at the time the API was defined.
It doesn't mean to unnecessarily expose implementation details, but I take it to be the other way around: implement things in a way that things work consistently without having to know the nuts and bolts.