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!
