I am an ERP Project Manager for 7 years within a big company which has many subsidiary companies. As ERP team, we are not only implementing ERP software but also writing our own ERP with the target that we sell this product in the future. Our platform is Java and our applications are web-based. Ibrahim has posted 11 posts at DZone. View Full User Profile

Beautiful API Design

11.26.2008
| 16763 views |
  • submit to reddit
When I first began to program in Java, I loved the Java language a lot. I used to program in Pascal, Delphi ,Visual Basic and C but Java was very different and elegant. In addition to its language structure and features, its API set was very special. With its beautiful and aesthetic design, programming in Java is a pleasure. I don’t have this feeling when I program in other languages. To feel pleasure or pain is also valid when we use API sets. There are many API sets we use in any development cycle coming from different frameworks or libraries. API beauty depends on designer knowledge and design capability (say artistic skill).

We use following principles when developing an API, a UI or a product (I used the word "Beautiful" since this includes following features):

· Simplicity: This kind of API is simple enough to meet programmer expectations. No extra lines, no extra methods, no extra parameters. It should contain only what you need today and tomorrow. If you are developing API, you should repeatedly ask the question “Can I shorten API without losing functionality?

· Maintainability: If I provide this API, can I support it without any problems. Is any change going to make it depreciated in the coming development? Some APIs may endanger other parts of the software and some of them are much more exposed to errors. When releasing an API, its usage should be thoroughly considered. Sometimes, API users may use it in some places that you never planned.

· Aesthetic: If we believe software development is art, aesthetic is its one of the main aspects. Goods or items in physical world have design and form aesthetic. We similarly have forms and designs in software not with materials but with API’s. To be aesthetic; API should be consistent, best names should be selected, understanding of function should be minimal, using API should make you comfortable.

· Functionality: One API set should solve as many problems as it can. Sometimes we see that similar needs are separately met by different API sets whereas one set of APIs may be enough. This topic is somewhat related with efficiency. Designed APIs should provide maximum reusability. One API set should provide as much functionality as it can with minimum code. We read many lines of code everyday and we see that a lot of boilerplate code (smelly code) is needed in some frameworks or API sets.

· Consistency: Same problems should be solved with the same attitude and way. Behaviors of your API should not change among classes or packages. You should use same pattern throughout your API set although there are many patterns for the same problem. For example your exception management style should be same in API set.

To design “Beautiful API”, one designer should take into consideration following points:

1- Keep it simple. Do only what is needed at the moment while thinking extensibility for future possible requirements as well. APIs should be easy to understand.

2- API designer must develop and empower himself in programming skills by reading others code and writing code continuously. One should learn as much as possible about topics like design patterns, API design principles and OOP principles. Skills should be certified with certification exams if possible. This gives some objective notion about skill development.

3- When designing an API, the cost associated with API development, bringing it into use, runtime resource consumption, user (programmer) education and support should be carefully considered and planned.

4- Before delving into API design, technological analysis and research should be done. Related references should be investigated and inspected taking notes. Research documents should be read before starting API design. Other similar API’s could be read for better API design. If this reference research is not done, "inventing wheel" never ends.

5- If API design requires a lot of work without any real benefit, it should be avoided. This will be a dangerous situation for both API designer and user. Additionally, an API sometimes can’t meet requirements as desired. In this situation, an API may be suspended temporarily and a workaround may be found for the requirement. When bringing the API into use, it should be monitored for "Bad Smell" taking feedback from programmer.

6- "Naming" should be carefully done. Names are the most important aspect of API design. Every name (DB Table - Column, Class, Method, Member and Parameter) should be considered as delicate as it is given to a newborn baby. Names must be searched in related literature.

7-
Designed API should be peer-reviewed before usage if possible.

8-
API should be tested and used in a reference implementation.

9-
API can be used without any configuration or maintenance (Zero maintenance).

10-
Unused API should be removed from API set. Any dead API confuses API designer and user in the future.

11- API should be documented and used as many places as possible. Sometimes its usage may be enforced.

12- API should be designed concretely that it must not change after release.

There are many good API design articles around the web. I recommend following resources for API designers:

http://www.infoq.com/presentations/effective-api-design
http://video.google.com/videoplay?docid=-474821803269194441
http://blogs.msdn.com/kcwalina/archive/2007/03/29/1989896.aspx
http://www.artima.com/forums/flat.jsp?forum=106&thread=142428

http://www.amazon.com/Practical-API-Design-Confessions-Framework/dp/1430209739
http://www.amazon.com/Framework-Design-Guidelines-Conventions-Development/dp/0321545613/ref=sr_1_1?ie=UTF8&s=books&qid=1227599123&sr=1-1
http://www.amazon.com/Beautiful-Code-Leading-Programmers-Practice/dp/0596510047
References
Published at DZone with permission of its author, Ibrahim Levent. (source)

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)

Comments

Mario León replied on Wed, 2008/11/26 - 11:00am

Excellent article, I'm totally agree with the points you expose here.

I had developed support API's for different applications, and the "tips'n tricks" you provide shows what has to be taken into consideration when doing this kind of job.

 Specially I'd say that significant names and a good level of abstraction will enhance any API greatly

Gian Franco Casula replied on Thu, 2008/11/27 - 4:45am

With new code and refactorings I always try to keep the teachings of Joshua Bloch in mind, regarding every programmer being an API developer...there is also a google techtalk, and he has given his presentation here in Europe as well...more than one our of pure gold.

Keeping these practices in mind and verifying your API against them is, in my opinion, a primary requirement for software professionals who take their craftmanship seriously.

Your article is great, and summarizes these point very well!

Ming Shing replied on Thu, 2010/11/25 - 4:54am

These two classes are interfaces in the API, pass4sure HP0-Y25, pass4sure 650-026, pass4sure 650-322 and every chic that is a beheld account on the map extends from one of those two.

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.