How to Design a Good API: Advanced Object Oriented Programming

Design a good API takes both engineering and artistic skills and is a well know challenge among experts of object oriented programming (OOP). This is a relatively advanced topic. Therefore, If you are unfamiliar with the concepts this article will give you the basic of OOP.

An Application Program Interface (API in short) refers to a set of functions and procedures allowing the creation of applications that access the features or data of an operating system, application, or other service.

A good API should be:

• Easy to learn and use. It should not intuitive enough to that the documentation would not be needed for the majority of the cases.
• Hard to misuse. At the same time an API should be designed in a way that prevent misuse of the code. in other words it should force you to do “the right thing”
• Easy to read and maintain code that uses it. As the API will change over time you would like to minimize the changes that users will have to do/
• Sufficiently powerful. It should be able to satisfy the requirements of your users and mask the complexity behind. In other words the users should be able to solve their needs without knowing all the details of how the system works.
• Easy to evolve. As requirements will change over time the API should accommodate these changes without causing major disruptions in the code that is wrapping as well as in how the users are using it.
• Targeted to the appropriate audience. As different groups of people use different terminologies the API should take into account these aspects. In other words, what is good for a physicist may not be good for an economist.

This google tech talk share some insight on the process and the best practices around the design of a good API.

Joshua Bloch has an extensive experience in this matter and show how good APIs increase the pleasure and productivity of the developers who use them, the quality of the software they produce, and ultimately, the corporate bottom line.