How to design a good API and why it matters (notes)

* 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...