> For the complete documentation index, see [llms.txt](https://hanfak.gitbook.io/workspace/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hanfak.gitbook.io/workspace/general-paradigms/patterns/api/aims.md).

# Aims of API designs

* List of aims for apis, some of these are at odds with each other:
  * intuitive
  * understandable
  * learnable
  * discoverable
  * consistent
    * method arguments
    * method names - should make sense
  * self defensive
  * concise
  * easy to use
  * minimal
  * orthogonal
  * idiomatic
  * flexible
  * evolvable
  * well documented
    * The api should not require to the docs to be read first to be able to use it
    * Docs should not be what or how it does, the signature and method body will tell you that
      * this increases the bloatness of code base
    * Say why
      * why was the choice made to do it this way if it is not obvious
    * Examples of what to put in
      * Give preconditions
      * postconditions
      * ranges of input
      * what happens when illegal values are added etc ie exceptions
      * Any side effects
      * Thread safe or not
    * Without can lead to question marks from users
  * right level of abstraction
  * correct use of type system
  * limited number of entry points
  * respect principle of least astonishment
    * Example of breaking this is Optional.of and ofNullable
* If in doubt, leave it out
  * otherwise
    * can create 100s hour of support
    * bloat software
    * confuse users
    * become burden
    * prevent future improvements
  * "it's easy to build" is not a good reason to add it
  * Have to understand that it impacts and works with other features, and is used by others