Fundamentals of good API designing

Do you write reusable OO code? Code that is being used by other modules within the same product? Or code that is exposed to the outside world and used to develop third party applications? If the answer to either of the questions is true, then you are an API developer. Either you write private APIs (used internally by other modules) or public APIs (used to develop other applications). Here are the fundamental principles which you should keep in mind while designing an API:

1. Understand the requirement:

Once you get the requirement from customer (a real “external” customer or the developer sitting next to you and working for the other module), break it up into small
 
use cases. That will help you to start thinking about the first few basic APIs.

2. Think and discuss:

  • Are you missing any use case? I am sure, at this stage, the answer might be yes. Revisit the requirements again. Think twice. That way you will be able to identify few more APIs.
  • Once you have the preliminary list ready, write it down and send it to others (as many as possible). Discuss. This is the most important part of API designing.
  • Listen carefully to what others are saying/suggesting. Remember once you write and expose your API to the outside world, you can’t change them. So, it’s better to debate, decide and then develop.

3. Not too many, not too less:

At the end of step 2, you might have a long list. Possibly one API per use case. Number them. Do you really need those many APIs? Is it possible to combine the functionality of few of them into one? That way you may end up writing more generic API. However, your API should not try to do too many things together. Remember all of us hate complexity.

4. Name them:

  • A meaningful, easy to understand, self-explanatory name helps the user to use it even without reading the documentation. A complicated name indicates that you are trying to do too many things (which are not a good design).
  • It should be consistent with the names of other existing APIs. Otherwise user may get confused.

5. Signature:

  • Design the signature in such a way that it could be extended in future (Use generic, enum, var-arg etc).
  • The way an API needs to be used should be very obvious. A user (developer) always hates surprise!

6. Prototype it:

Are you sure that your thoughts can be converted into real code? Write (code) a prototype.

7. Implement:

  • Not sure about a validation/functionality? don’t add it. A less restrictive approach is always better to start with.
  • While coding consider not only about the behavior, but also about the performance.
  • Hide implementation details. Don’t expose exceptions which talk about internal implementation. API should throw exceptions which is relevant to the APIs external behavior and not to the internal behavior.

8.  Document it:

  • Document every small thing. Do it religiously. Document each and every contract, limitation, pre & post conditions.
  • But, don’t over explain. Keep it short and crispy. Exposing implementation details might be confusing. You may need to change the implementation in future, so it’s better not to talk about it.

9. Test it:

This is where your API will be used for the first time.

10. Use it:

Is it possible to consume the API even before exposing it to the outside world? If yes, please do it. This is your last chance to make things correct. Once exposed, you will never be able to change the external behavior. However, it will take some time (read few releases) for the internal implementation to get stable. Remember, Rome wasn’t built in a day!
 

Reference: Fundamentals of good API designing from our JCG partner Arnab Biswas at the Death By Code blog.

Do you want to know how to develop your skillset to become a Java Rockstar?

Subscribe to our newsletter to start Rocking right now!

To get you started we give you two of our best selling eBooks for FREE!

JPA Mini Book

Learn how to leverage the power of JPA in order to create robust and flexible Java applications. With this Mini Book, you will get introduced to JPA and smoothly transition to more advanced concepts.

JVM Troubleshooting Guide

The Java virtual machine is really the foundation of any Java EE platform. Learn how to master it with this advanced guide!

Given email address is already subscribed, thank you!
Oops. Something went wrong. Please try again later.
Please provide a valid email address.
Thank you, your sign-up request was successful! Please check your e-mail inbox.
Please complete the CAPTCHA.
Please fill in the required fields.

Leave a Reply


5 × = fifteen



Java Code Geeks and all content copyright © 2010-2014, Exelixis Media Ltd | Terms of Use | Privacy Policy | Contact
All trademarks and registered trademarks appearing on Java Code Geeks are the property of their respective owners.
Java is a trademark or registered trademark of Oracle Corporation in the United States and other countries.
Java Code Geeks is not connected to Oracle Corporation and is not sponsored by Oracle Corporation.
Do you want to know how to develop your skillset and become a ...
Java Rockstar?

Subscribe to our newsletter to start Rocking right now!

To get you started we give you two of our best selling eBooks for FREE!

Get ready to Rock!
You can download the complementary eBooks using the links below:
Close