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

1 comment so far

  1. […] The Plan A: A good API mustAll very good points on API design which can be seen in action within most popular Ruby projects. The point on good APIs being “Easy to use, even w/o doc” gives weight towards creating fluent-interfaces. “Easy to read and maintain code that uses it” definitely reminds me of the benefits to code-readability that DSL(-like) APIs yield. […]

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: