> "easy" API's generally do it by making a ton of assumptions.
Well, perhaps a better way of putting it is that "easy" APIs try to model a ___domain. Sometimes the API designer just nails it, and folks forget eventually take it for granted. The problem is now "solved". For example, the Unix userspace filesystem API (open, close, read, write, etc.) is pretty damn solid for what it is. I admit that I took it for granted until I worked at a place where someone who'd never seen a filesystem API (!!) was tasked with creating one from the ground up. You can guess how that went.
The downside case is where the API's model either never cut it in the first place, or as @wtallis illuminates above with OpenGL, where the model just ages poorly[1].
Well, perhaps a better way of putting it is that "easy" APIs try to model a ___domain. Sometimes the API designer just nails it, and folks forget eventually take it for granted. The problem is now "solved". For example, the Unix userspace filesystem API (open, close, read, write, etc.) is pretty damn solid for what it is. I admit that I took it for granted until I worked at a place where someone who'd never seen a filesystem API (!!) was tasked with creating one from the ground up. You can guess how that went.
The downside case is where the API's model either never cut it in the first place, or as @wtallis illuminates above with OpenGL, where the model just ages poorly[1].
[1] https://news.ycombinator.com/item?id=9194138