A good API must :

 Ruby have a very good set of features to desing API and thats why rails and other pseudo-DSLs make us feel really comfortable.  Closures/code blocks,  metaprogramming and method_missing method are the mos important.

I have been watching Joshua bloch track “how to design a good api and why matters” , its a really iteresant video. I must think about some points :

• Easy to learn
• Easy to use, even w/o doc
• Hard to misuse
• Easy to read and maintain code that uses it
• Sufficiently powerfil to satisfy requirements
• Easy to extend
• Appropriate to audience – no such thing as a “perfect” API for everyone

When we design an API we must :

• Start with a small (1 page) spec
• TDD for API design
• Minimize accessibilty – maximize information hiding
• Class Design
  • Minimize mutability
  • If mutable, keep the state space small and well defined
• Method design
  • Spending time on the API to make it easier is more important than performance
  • Provide programmatic access to all data available in String form
  • Overload with care – no two with same number of args
  • Use consistent parameter ordering
  • Don’t use exceptions for control flow, only for errors