designing apis for others

©

e S

y m

m e

t r

i

x

Designing APIs for OthersReal World Lessons About

Commercial API Development

©

e S

y m

m e

t r

i

x

Typical Programming Goals

• Minimize maintenance cost & risk

• Extensible / refactorable to new requirements

• Easy to read the source code

©

e S

y m

m e

t r

i

x

Commercial API Goals

• Other people use your library and like it.

• Short First Reference -> First Wow

• Digestible, iterative discovery

Easy Things are Easy, Hard Things are Possible

©

e S

y m

m e

t r

i

x

How Users Discover

• Code Samples– Very narrow, taken literally

• IntelliSense Driven Discovery• See that they probably can do what they want

to.

©

e S

y m

m e

t r

i

x

Design Priorities

• Discovery through your fingers• Where possible can’t be misused• Don’t show what they don’t need– Advanced features in advanced ways

• Hard Shell– Designer->Compile->Runtime

©

e S

y m

m e

t r

i

x

Key Implementation Method

• Always outside in – terms, flow, exception types.

• Reads like the outline of a book– Fewer, Flatter

• Sample Driven Development– Samples are your test cases– Digestible chunks of WHY

• Consistency

©

e S

y m

m e

t r

i

x

Inheritance

• Awkward IntelliSense• Hardening Tricky• Alternating viewpoints (External & Internal)• Compromise Simplicity

Advanced User Cool FactorCustomer Request Safety Net

©

e S

y m

m e

t r

i

x

Exceptions

• Thrown at very predictable points

• Use intrinsic types wherever they can fit– Pick types that make sense from the outside– Custom types are great for internal exceptions

caught & re-thrown

©

e S

y m

m e

t r

i

x

Hardening

• Event Pattern• Property Transitions• Inheritance

©

e S

y m

m e

t r

i

x

FxCop

• Catches all manner of subtle things• You can ignore its advice – but know why– Use of generic event handlers– Exposing generic collections

• Samples too – don’t require users to break the rules

©

e S

y m

m e

t r

i

x

Packaging

• Fewer Assemblies• Runnable Sample Solution• Clear Redistribution Requirements• Xml Help, PDB if feasible• Unit tests if available

©

e S

y m

m e

t r

i

x

Common Mistakes

• Users aren’t as smart as you– Domain knowledge– Coding capability

• Internal / Tribe Language• Inconsistent– Framework + API + Experience

• Single Minded

©

e S

y m

m e

t r

i

x

Most Common Mistake

You must have at least two, independent external teams use your API while it’s still

changeable

©

e S

y m

m e

t r

i

x

Additional Information

Book– Framework Design Guidelines by Krzysztof Cwalina

Websites– www.GibraltarSoftware.com– www.eSymmetrix.com

Follow Up– Kendall.Miller@eSymmetrix.com– Twitter: kendallmiller