
How to design a good API and why it matters (notes) - udkl
https://www.youtube.com/watch?v=aAb7hSCtvGw
======
udkl
* You have one chance to get the API right

* API’s can make or break the company

* Everyone is an API designer. If you program, you are an API designer.

* Good API: Easy to use, learn, hard to misuse, just powerful enough, easy to evolve, appropriate for the audience (API terminology)

* Process

\- Gather requirements - Be Skeptical - Hear the un-said.

\- Convert requirements to use-cases

\- Start with a short spec - ideally 1 page

\-- Don’t create a long spec first time around - it gets associated with the
ego and then iterate

\- bounce it off of the stakeholders

* Write to your API early and often. Basically, write tests early. \- These probably will live on to become examples on how to use the API \- Make sure these are exemplary as the examples will be used by consumers to base off their code.

* Maintain realistic expectations \- You won’t be able to please everyone \- Aim to displease everyone equally

* Expect to make mistakes \- API design is hard \- Expect the API to evolve

* Principles of good API design: \- Should do one thing and do it well. \- Should be easy to explain. \- Should be easy to name

* Should be as small as possible but not smaller \- When in doubt, leave it out. \- It’s easier to add it later than to remove it.

* Implementation should not impact API

\- details confuse users

\- inhibit freedom to change an implementation

\--- eg: catching SQL exceptions by the client

\-- Do not let implementation detail leak into the API

\--- Eg: implements serializable - all private fields are now public after
serialization

* Minimize accessibility of fields

\- Make classes, fields as private as possible

\- public classes should not have any public fields, with the exception of
constants

\- Minimizes coupling

* Names matter

\- Names should be self-explanatory

\- Be consistent

\- Be regular- strive for symmetry

\--- If key and entry are two attributes, and addKey and removeKey are methods
on ‘key’ then there should be ‘addEntry’ and ‘removeEntry’

* Document religiously

\- Document every class, interface, method, constructor, parameter and
exception.

\- Method documentation : contract tween method and it’s clients : pre-
conditions, post-conditions, side-effects

\- Parameters : indicate ownership(can I modifiy it ?), units (size of blocks
in bytes), form (String : XML ? json)

* Document state space religiously

\---- 37 minutes in the video ---- To be continued...

