So, why are there so many bad APIs around? The prime reason is that, for every way to design an API correctly, there are usually dozens of ways to design it incorrectly.
Good API design is hard, while bad APIs are easy. Michi Henning's API Design Matters in May/June issue of ACM Queue is a comprehensive guide to designing good APIs.
He dissects the .NET socket
Select()function in C# and points out the deficiencies which many of our day-to-day usable frameworks have. The article also discusses the interplay of abstraction hierarchies with good api design.
Much of software development is about creating abstractions, and APIs are the visible interfaces to these abstractions. .. The lower in the abstraction hierarchy an API defect occurs, the more serious are the consequences.
And finally, the most important aspect of API design is to manage the expectations of the closure of users who will be exercising them. And once you have published your API, it becomes immutable. Can't agree more ..
A very good read ..