7 Lessons from “How to Design a Good API and Why it Matters”

Lessons from Joshua Bloch’s 2006 OOPSLA talk – “How to Design a Good API and Why it Matters”.

1. Public APIs are forever. (Yes, just like diamonds).

Customers invest heavily in buying, learning and integrating with a company’s APIs. The cost to stop using an API can be prohibitive. Done right, APIs are a huge asset to a company and capture customers. Done wrong, bad APIs result in an unending stream of support calls and become a liability.

2. Good APIs are easy to learn

Good APIs are easy to read, easy to use , easy to extend and hard to misuse.

3. At the design stage, design your API early and often.

Iterate quickly – agility trumps completeness. Bounce your specification and design off as many people as possible. Start your API design before you have implemented your API or even have all the requirements.

4. Expect to make mistakes.

Real world use will flush them out. So expect your API to evolve.

5. Names matter.

Names should be largely self-explanatory. Be consistent – same word should mean same thing throughout the API. Follow standard naming conventions.

6. Document religiously.

Document every interface, parameter and operation. Document state space.

7. Consider performance consequences of API design decisions.

Good design usually coincides with good performance.


Joshua Bloch. 2006. How to design a good API and why it matters. In Companion to the 21st ACM SIGPLAN symposium on Object-oriented programming systems, languages, and applications (OOPSLA ’06). Association for Computing Machinery, New York, NY, USA, 506–507. DOI:https://doi.org/10.1145/1176617.1176622

Leave a Reply