Things to consider while writing public APIs

When you expose public class/APIs, there are certain things that you need to consider

1. Arguments/Parameters
Carefully consider the arguments that gets passed into the API.

2. Method Name
Choose an apt meaningful name for the public methods or classes. Avoid ambiguity.

3. Exceptions
Throw only non-runtime exceptions, so that clients can handle them. Do try to handle all the exceptions in the method. If you have logging framework, log the exceptions and rethrow them.

4. Backward Compatibility
Once the APIs get released and you need to support them for an extended period of time. So if you modifying existing public APIs take care of backward compatibility, such that you wont break client code.

5. Intented use
The public APIs should do only what it is intended to do

6. Java docs
Provide clear crisp java docs. The best example is the one that comes with JDKs.

7. Trace / Log / Debug
Provide support for tracing/logging. Both serves different purposes. Trace is used to find the control flow inside the public APIs. Logging is used to log any error messages and exceptions.

8. Error statements
In case of wrong parameters getting passed, log descriptive error messages. The error message should typically say what went wrong and what is the corrective action.