DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
Refcards Trend Reports Events Over 2 million developers have joined DZone. Join Today! Thanks for visiting DZone today,
Edit Profile Manage Email Subscriptions Moderation Admin Console How to Post to DZone Article Submission Guidelines
View Profile
Sign Out
Refcards
Trend Reports
Events
Zones
Culture and Methodologies Agile Career Development Methodologies Team Management
Data Engineering AI/ML Big Data Data Databases IoT
Software Design and Architecture Cloud Architecture Containers Integration Microservices Performance Security
Coding Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Culture and Methodologies
Agile Career Development Methodologies Team Management
Data Engineering
AI/ML Big Data Data Databases IoT
Software Design and Architecture
Cloud Architecture Containers Integration Microservices Performance Security
Coding
Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance
Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
  1. DZone
  2. Data Engineering
  3. Databases
  4. Beautiful API Design

Beautiful API Design

Adam Brown user avatar by
Adam Brown
·
Nov. 26, 08 · News
Like (1)
Save
Tweet
Share
22.69K Views

Join the DZone community and get the full member experience.

Join For Free
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
API Design

Published at DZone with permission of Adam Brown. See the original article here.

Opinions expressed by DZone contributors are their own.

Popular on DZone

  • A Complete Guide to AngularJS Testing
  • Top 5 Node.js REST API Frameworks
  • How to Develop a Portrait Retouching Function
  • Why Every Fintech Company Needs DevOps

Comments

Partner Resources

X

ABOUT US

  • About DZone
  • Send feedback
  • Careers
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 600 Park Offices Drive
  • Suite 300
  • Durham, NC 27709
  • support@dzone.com
  • +1 (919) 678-0300

Let's be friends: