[tmurray]

The hardest part about API design is picking the appropriate primitives in the first place. Use cases are relatively easy--somebody has a problem, come up with a solution--but any solution can be expressed in a myriad of different ways. The way that the API designer expresses that solution to the users of the API will impact the way code is written.

Users generally won't understand the implementation of the API, so instead they build a model of how they think the entire system operates. In the process, they make assumptions about performance, side effects, etc. that may be totally incorrect. Good APIs anticipate these assumptions and make them relatively easy to predict with some level of experience, either from elsewhere in the API or from similar APIs.

[Rickasaurus]

I'd say that this is also where good documentation comes into play. Anyone who is going to be spending a lot of time with your API should be able to fully trust it and eventually have a strong understanding of how the system works by simply looking up things in the documentation.

If you're selling an API though, it's even more important that most users can just drop it in and forget about it. This is how you maximize evaluation to purchase conversions. The implication of this is you need to spend a lot of time thinking hard about what defaults would be best for most users. Of course, you don't always get this right off the bat but the sales and support teams will let you know pretty quickly how it's going after the initial release of a new product.