When I read your comment, I'm left with the distinct impression that we agree on 90% of what you're saying.
Of course you're going to document your API and define the format of what comes back from your requests. An API is a contract. Yeah, you isolate complexity in your API. You design an API, which is a difficult job, rather than just saying to your user, "here's a mapping to my database, do whatever you want with it."
This article does not say that APIs "should be vague about what they provide." It says the opposite, they should be very specific about what they provide.
You design an API by providing specific tools for your users. You give them hammers, not chunks of metal that they can mould however they want. You don't throw "features" into your API, you provide capabilities that your users need.
Mathieu