How To Design A Good API and Why it Matters
Google TechTalksYouTube ↗
Further reading 6
Small objects or small interfaces? →One talk breaks code into smaller responsibilities. The other limits what callers must learn. Count the decisions exposed to callers as well as the objects inside the implementation.When does a module boundary freeze a decision? →An interface can shelter callers from a changing implementation. Once clients depend on its behavior, changing the interface itself becomes more expensive.Does hiding mutation remove coordination costs? →An object can conceal its state and still require callers to coordinate operations. Examine what happens when independently safe operations must work together.Which choices should an API leave out? →Removing an uncertain feature reduces what clients must learn. Separating tangled concerns reduces how many choices they must consider together.How much can a small interface hide? →A small API reduces the concepts callers must learn. A deep module makes that small surface useful by hiding substantial implementation behind it.When does an implementation detail become a promise? →Interpreter behavior, hash tables and public APIs illustrate how callers come to rely on what they can observe. Observable behavior need not have been formally guaranteed.
Caption notes
Bloch recommends designing APIs around concrete uses, testing them with clients early and omitting doubtful features before compatibility makes removal difficult.
Original passages · 7
you should start before you've
implemented the APInot be able to take it out once you put it into an API.don't make the client do
anything the module could do.programmatic access to
all data that is also available in string form.feels like an immutable
object, except that it has state inside it.APIs can be among a company's greatest assetsWhen it doubt, leave it out.