# API

* Creating apis is probably the main thing that java is used for
  * Web api
  * library api
* An API is what developers use to achieve some task
  * is useful as used by other software, and resusable
* it establishes a contract between them and the designers of the software, exposing its services through that API.

## Characteristics of good api

* should be easily understandable and discoverable
  * It should be possible to start using it and, ideally, learn how it works without reading its documentation
  * Having example tests is a good replacement for documentation
* it’s important to use consistent naming and conventions.
* Keeping your API minimal is another way to make it easy to use.
* using factory methods instead of constructors is another valuable practice since it allows greater flexibility:
  * you can also return an instance of a subclass or even a null when the method is called with illegal arguments.
* principle of least astonishment should be observed
  * It should do what is expected
  * Example, Optional.of(T t) breaks this as throws nullpointer when t is null, thus needs Optional.ofNullable(T t). When only one method would be needed
* break apart large interfaces into smaller pieces;
* consider implementing a fluent API,
* never return null
  * emptylist or optional instead
* limit usage of exceptions, and possibly avoid checked ones
* Regarding method arguments:
  * avoid long lists of them, especially of the same type;
  * use the weakest possible type;
  * keep them in consistent order among different overloads;
  * consider varargs