There's a school of API design that believes you can guide users to reflect on what they are doing by deliberately excluding certain things, without explaining why they are absent.
This springs from a prescriptive viewpoint that presumes the reader will inevitably arrive at the same conclusions as the author about the right way to do things.
Since no one is always right, and API's are too often designed without considering what actual application usage would be like, this can be extremely frustrating.
The best API's that somehow hit the sweet spot of minimal, efficient, and obvious are always extremely impressive.
This springs from a prescriptive viewpoint that presumes the reader will inevitably arrive at the same conclusions as the author about the right way to do things.
Since no one is always right, and API's are too often designed without considering what actual application usage would be like, this can be extremely frustrating.
The best API's that somehow hit the sweet spot of minimal, efficient, and obvious are always extremely impressive.