Application Programming Interface (API) design is hard. But it's even harder to change once you get it wrong. So what you should do is to spend the effort to get it right the first time around.
In the Linux Kernel community Rusty Russell came up with a API rating scheme to help us determine if our API is sensible, or not. It's a rating from -10 to 10, where 10 is perfect is -10 is hell. Unfortunately there are too many examples at the wrong end of the scale.
10. It's impossible to get wrong.
9. The compiler/linker won't let you get it wrong.
8. The compiler will warn if you get it wrong.
7. The obvious use is (probably) the correct one.
6. The name tells you how to use it.
5. Do it right or it will always break at runtime.
4. Follow common convention and you'll get it right.
3. Read the documentation and you'll get it right.
2. Read the implementation and you'll get it right.
1. Read the correct mailing list thread and you'll get it right.
-1. Read the mailing list thread and you'll get it wrong.
-2. Read the implementation and you'll get it wrong.
-3. Read the documentation and you'll get it wrong.
-4. Follow common convention and you'll get it wrong.
-5. Do it right and it will sometimes break at runtime.
-6. The name tells you how not to use it.
-7. The obvious use is wrong.
-8. The compiler will warn if you get it right.
-9. The compiler/linker won't let you get it right.
-10. It's impossible to get right.