Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share

locked by Yannis Rizos Aug 4 '13 at 10:06

This question exists because it has historical significance, but it is not considered a good, on-topic question for this site, so please do not use it as evidence that you can ask similar questions here. This question and its answers are frozen and cannot be changed. More info: help center.

closed as too broad by gnat, BЈовић, Yannis Rizos Aug 4 '13 at 10:06

There are either too many possible answers, or good answers would be too long for this format. Please add details to narrow the answer set or to isolate an issue that can be answered in a few paragraphs.If this question can be reworded to fit the rules in the help center, please edit the question.

1  
Could you list some "great API"? Personally I am regularly positively surprised by Qt. –  Ubiquité Apr 9 '11 at 19:30
    
The Sinatra web application framework is my favourite API. It does one thing and does it well. –  dodgy_coder Jun 21 '12 at 2:39
comments disabled on deleted / locked posts

6 Answers 6

up vote 17 down vote accepted

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.

share
add comment

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.
share
3  
+1 for consistency –  Falcon Apr 10 '11 at 10:34
    
+1 for documentation –  Aditya P Apr 10 '11 at 11:16
    
Consistency should be no. 1 thing. Docs come second –  good_computer Jul 27 '11 at 12:27
    
Consistency applies to languages as well: my dislike of PHP and JavaScript is mainly for their lack of consistency. –  dodgy_coder Jun 21 '12 at 2:33
add comment

Great APIs have great documentation.

share
1  
+ 1 Yep. The most important point. –  Aditya P Apr 10 '11 at 11:15
add comment
  • Do one thing and do it great.
  • Easy to use, difficult to misuse.
  • Easy to extend.
  • Well documented.
  • Consistent style.
share
add comment

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

share
add comment

The simplest useful interface and good naming conventions.

share
add comment

Not the answer you're looking for? Browse other questions tagged or ask your own question.