Friday, March 2, 2012

Designing a good API

What is an API
An application programming interface (API) is a source code-based specification intended to be used as an interface by software components to communicate with each other. An API may include specifications for routinesdata structuresobject classes, and variables.
Why is a an API important
All developers have third party products they prefer to work with. Why do we prefer working with some products, but not other?
Often it comes down to the fact that some products are easier to work with than others. They have better documentation, more intiutive methods and just seem more professional than others. 
A bad API causes neverending support request and will in the end become a liability for a company.
What is a good API
A good API is
  • Easy to learn
  • Easy to use
  • Hard to misuse
  • Easy to read 
  • Easy to maintain code that uses it
  • Easy to extend
General principles when designing an API
  • Do one thing and do it well
    • Functionality should be easy to explain
    • If it's hard to name, consider rethinking the design
  • Keep it small
    • An API should satisfy it's requirements
    • When in doubt leave it out
  • Implementation shouldn't impact API
    • Implementation details
    • Don't let implementation details leak into the API
  • Minimize accessibility
    • Make classes and members as private as possible
  • Names should be self-explanatory
  • Documentation mathers
    • Document every class, interface, method, constructor, parameter and exception
Exception design
  • Throw exceptions to indicate exceptional conditions
  • Don't force clients to use exceptions for control flow
  • Don't fail silently

No comments:

Post a Comment