4 ms·

So, you want to provide an API for the world to use?

58 points by mgunes 16y ago

deleted 16y ago
[deleted]
pietrofmaggi 16y ago
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 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
- deleted 16y ago
  [deleted]
chrisbaglieri 16y ago
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 16y ago
  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 16y ago
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 16y ago
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 http://www.infoq.com/presentations/effective-api-design

58 points by mgunes 16y ago

deleted 16y ago

[deleted]

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 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

deleted 16y ago
[deleted]

chrisbaglieri 16y ago

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 16y ago
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 16y ago

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 16y ago

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 http://www.infoq.com/presentations/effective-api-design