
So, you want to provide an API for the world to use?  - mgunes
http://design.canonical.com/2010/12/so-you-want-to-provide-an-api-for-the-world-to-use/
======
pietrofmaggi
On the same subject I've found very useful "The Little Manual of API Design"
by Trolltech (the makers of Qt): <http://chaos.troll.no/~shausman/api-
design/api-design.pdf>

The documents start stating some characteristics of Good APIs:

    
    
      1. Easy to learn and memorize
      2. Leads to readable code
      3. Hard to misuse
      4. Easy to extend
      5. Complete

------
chrisbaglieri
While not an attribute of an API itself, providing libraries in a variety of
languages or supporting libraries developed by your users also plays a
critical role in uptake.

~~~
bluedevil2k
Agreed. Most use case scenarios will involve a code library wrapper around the
API. There's some unique challenges in building the library as well though -
in a small & quick start-up, it might be hard to find experienced programmers
in the 7-10 languages you'd want to support. When you get an experienced PHP
developer to write the Java API, it will work, but will it "work"? In other
words, will it follow the conventions that Java programmers are used to
(classes, objects as parameters, static methods, etc.), or will it simply be
ported PHP code to Java (hashtables as parameters to every method, fewer
objects, etc.).

I've often said you can tell how good a code library is for an API based on
how often the user needs to read the API documentation - ideally, they would
never need to even read the API. After all, why have a code library if the
users still need to look up the exact spelling and capitalization scheme of
string parameters, or look up the numerical codes in return values?

------
sammyo
I liked Joshua Bloch's point that during development there should be at least
two-three different apps that excercise the api preferably developed by
different developers.

------
metachris
I've found this talk by Joshua Bloch about "How To Design A Good API and Why
it Matters" very inspiring and and helpful:
<http://www.infoq.com/presentations/effective-api-design>

