API dos and don'ts
This page describes some common errors and mistakes when working with APIs.
Create AbstractYourProjectAPIImpl. Always. There were not project yet, where a common abstract api implementation wasn't needed. And that common abstract api implementation should extends the one that we already have:
Don't create exception types for each api.
At least don't let them extend Exception if you do. Why? Because having incompatible exception types will force one api, that uses another api to catch that api's exceptions, and re-throw them. This will leave to a lot of boilerplate code. Since API is generally syndication of services, it doesn't matter which API through an Exception. Example:
Consider we have 2 APIs, which depend on each other.
and the MessageAO like that:
now to synthesize this MessageAO the MessagingAPI would perform something like this.
Obviously the second catch block is obsolete. If both APIs would declare to throw APIException, than it would be easy to throw the Exception through.
Another advantage of declaring all exceptions as APIException is that than a general type of Exceptions can be used, like:
This would allow you to handle all backend errors, which you can't handle anyway, at once place.
Of course, you can still have MessagingAPIException, and you can still use it, and even catch it, but not having it in the throws clause helps a lot.
So the proper way to do it would be: