In 2006 (yes, before the RESTful era), Joshua Bloch gave a talk entitled “How to Design a Good API and Why It Matters.” While it’s not directly applied to RESTful design, Joshua’s list of “Characteristics of a Good API” is extremely applicable. Watch the YouTube video below to hear the talk (this one’s from 2007). My own summary of important points is at the bottom of the post.
Here is a brief checklist summarizing Joshua’s “Characteristics of a Good API”:
- Easy to Learn
- Easy to use, documented or not
- Hard to use incorrectly
- Easy to read, understand and maintain the code that uses it
- Just enough power to satisfy requirements
- Easily extensible
- Appropriate for the audience