is controversial to me, as I have alluded to here
I like API's to be simple, straight forward, and they need to involve as little 'theory of operations' as possible. In my question above, it turns out IO:All blocks the user from doing something nonsensical, yet, the API intrinsically implies such a thing is possible. (Not to be picking on IO::All, I'm just using it as an example).
Another API discourse -- Many API's, for example Linux PAM have a rather bad 'theory of operations', meaning you have to call a lot of functions in a certain order to get things right. I like functions to be one-shot-one-kill and do what they say, in the right context. Required domain knowledge should be internal to the API methods, not be forced upon the caller. Java methods are typically the anthithesis of this, requiring tons of methods across various classes to get any functional unit of work done. Brevity and simplicity in the interface is lacking. IO::All does a good job here (most API's don't), and it even does checking to block the crazy implications of routing a directory to a socket, there is another issue.... normality and obviousness.
If you didn't have the documentation, and only the method names, you should know exactly how it works and it should work as expected. You also shouldn't be able to blow your leg off, much less shoot yourself in the foot.
As for breaking API's, I've seen this done to me millions of times and it annoys me to no end. Not in Perl, but C++. I guess a good way to start in Perl it to have most functions take named parameters (hashes) and not to change method signatures. But that takes discipline and up-front design -- not everyone is into that. With C, have your functions take structures and add to the end of them to preserve binary compatibility -- but even this can be hard. It's design-up-front. Not always easy to see the future.
But in all, it's an artform, and stringency that removes fun and coolness isn't always worth it. IO::All has some cool ideas, but it walks a fine line between cool and too cool. But is there such a thing as too cool? Only for production work.