by
Join the DZone community and get the full member experience.
Join For FreeWhen 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
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
API
Design
Published at DZone with permission of Adam Brown. See the original article here.
Opinions expressed by DZone contributors are their own.
Comments