4 ms·
* 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. * Go
by udkl 11y ago
* 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...