2 ms·

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

4 points by udkl 11y ago

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

4 points by udkl 11y ago

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