In this post on Medium.com Gediminas Rapolavicius provides a word of warning to those creating APIs (interfaces for tools, not like REST APIs) - "don't try to be too smart", favor consistency over cleverness.

When designing an API, it’s tempting to do a bit of extra work and surprise the developers using it. It might be returning some additional information that would require an additional call otherwise, or try to predict the intentions and handle some specific cases differently. The intentions are perfectly fine?—?provide a pleasant, simple interface.

The problem is that it requires making assumptions which, sometimes, are inevitably wrong. The worst case is when the API makes an assumption of what the developer expect to get back, gets it wrong, and returns something unexpected. More work with docs, more bug fixing.

He gives two examples of things he's encountered where the idea of the API was simple but assumptions made turned out to make things a bit more difficult: PHP's own array_rand function and WordPress' update_post_meta. He briefly covers each and explains that, while the intentions seemed good, the implementation was a bit confusing (and at times inconsistent), causing troubles when not functioning as expected.