What do great APIs have in common?

Question

What is it about great APIs that makes them great? I think that adhering to the "do one thing and do it well" mantra is a good sign and being is a good mapping to the problem domain is important, but what do great APIs have in common?

Answer 1

You have to be careful to avoid adding new vocabulary just for the sake of your API. My favorite APIs explain things to me in vocabulary I already understand. Along those lines:

Don't add too many abstractions on top of what you're building on. Keep it simple.

I already have to think about about half-a-dozen layers of abstraction. Dont make me think about extra layers. Don't give me too many new things to learn that won't add value to my end goal. For example, avoid using your own special file class that works differently then the language's file type just cause you think your way is better than the generally accepted way. Stick with the generally accepted way, at least in your interfaces, for better or for worse.

Stick with concrete ideas

For example don't try to hide the fact that the "model" part of your MVC framework is a front end for a database. Take advantage of the well known vocabulary surrounding "databases". I know what foreign keys are. I know what rows and columns are. Talk to me in these terms.

Don't abstract out essential knowledge

Similar to working with concrete ideas. Don't hide the fact that we're dealing with files or databases or rows in databases. I know these things. If I'm dealing with a container, like a List, there's a good chance I need to know the algorithmic complexity of common operations. You can simplify that a lot by just telling me its a "linked list" or an "array". A huge set of ideas will suddenly be brought to bear on what you're doing and it'll all suddenly make sense. Don't create your own set of ideas that I have to learn when I'll already come with a rich and useful set of terminology to apply to the problem.

Reduce the number of terms I need in my vocabulary

If I'm using your API to open an image file of any type, I shouldn't have to think about pngs vs gifs vs jpgs very much. You'll do that for me. Its your core competency, not mine. I have some vague understanding that you have some magic to do this for me.

Answer 2

A useful API has the following:

• Concise and thorough documentation. If I'm searching on how to implement a task, I'm able to find out if the API has the capability to do so, within a couple of minutes. This is achieved by the brevity of the text and the layout of the resource. The documentation provides examples on how to use it and also makes no assumptions on the readership.
• An large, active community. I'm stoked when I find forums, IRC channels, mailing lists, etc. with active participants willing to help out the new guys. I understand that this is usually the case for larger projects, but still, would be something to strive for.
• Consistency. When I'm actually using the API, I don't want to be shocked in any way when I call a method, or discover that method X is completely different from the convention set by the rest of the API.

Answer 3

Great APIs have great documentation.

Answer 4

• Do one thing and do it great.
• Easy to use, difficult to misuse.
• Easy to extend.
• Well documented.
• Consistent style.

Answer 5

This question is addressed in "Practical API Design: Confessions of a Java Framework Architect" by Jaroslav Tulach from the NetBeans team.

Answer 6

The simplest useful interface and good naming conventions.