designing for others- commercial api design (nyc code camp)
DESCRIPTION
TRANSCRIPT
©
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
IntelliSense Discovery Demo
©
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 Demo
©
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
Hardening Demo
©
e S
y m
m e
t r
i
x
FxCop / VS Code Analysis
• 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
• FxCop free in the Windows SDK, VS Code Analysis in Pro & higher editions.
©
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– [email protected]– Twitter: kendallmiller