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.
Related Whitepaper:

Software Architecture

This guide will introduce you to the world of Software Architecture!

This 162 page guide will cover topics within the field of software architecture including: software architecture as a solution balancing the concerns of different stakeholders, quality assurance, methods to describe and evaluate architectures, the influence of architecture on reuse, and the life cycle of a system and its architecture. This guide concludes with a comparison between the professions of software architect and software engineer.

Get it Now!  

Leave a Reply


nine − = 1



Java Code Geeks and all content copyright © 2010-2014, Exelixis Media Ltd | Terms of Use
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.

Sign up for our Newsletter

15,153 insiders are already enjoying weekly updates and complimentary whitepapers! Join them now to gain exclusive access to the latest news in the Java world, as well as insights about Android, Scala, Groovy and other related technologies.

As an extra bonus, by joining you will get our brand new e-books, published by Java Code Geeks and their JCG partners for your reading pleasure! Enter your info and stay on top of things,

  • Fresh trends
  • Cases and examples
  • Research and insights
  • Two complimentary e-books