designing apis for others
DESCRIPTION
Real World Lessons about Commercial API DevelopmentTRANSCRIPT
![Page 1: Designing APIs for Others](https://reader036.vdocuments.us/reader036/viewer/2022081519/5565e436d8b42a20638b4797/html5/thumbnails/1.jpg)
©
e S
y m
m e
t r
i
x
Designing APIs for OthersReal World Lessons About
Commercial API Development
![Page 2: Designing APIs for Others](https://reader036.vdocuments.us/reader036/viewer/2022081519/5565e436d8b42a20638b4797/html5/thumbnails/2.jpg)
©
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
![Page 3: Designing APIs for Others](https://reader036.vdocuments.us/reader036/viewer/2022081519/5565e436d8b42a20638b4797/html5/thumbnails/3.jpg)
©
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
![Page 4: Designing APIs for Others](https://reader036.vdocuments.us/reader036/viewer/2022081519/5565e436d8b42a20638b4797/html5/thumbnails/4.jpg)
©
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.
![Page 5: Designing APIs for Others](https://reader036.vdocuments.us/reader036/viewer/2022081519/5565e436d8b42a20638b4797/html5/thumbnails/5.jpg)
©
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
![Page 6: Designing APIs for Others](https://reader036.vdocuments.us/reader036/viewer/2022081519/5565e436d8b42a20638b4797/html5/thumbnails/6.jpg)
©
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
![Page 7: Designing APIs for Others](https://reader036.vdocuments.us/reader036/viewer/2022081519/5565e436d8b42a20638b4797/html5/thumbnails/7.jpg)
©
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
![Page 8: Designing APIs for Others](https://reader036.vdocuments.us/reader036/viewer/2022081519/5565e436d8b42a20638b4797/html5/thumbnails/8.jpg)
©
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
![Page 9: Designing APIs for Others](https://reader036.vdocuments.us/reader036/viewer/2022081519/5565e436d8b42a20638b4797/html5/thumbnails/9.jpg)
©
e S
y m
m e
t r
i
x
Hardening
• Event Pattern• Property Transitions• Inheritance
![Page 10: Designing APIs for Others](https://reader036.vdocuments.us/reader036/viewer/2022081519/5565e436d8b42a20638b4797/html5/thumbnails/10.jpg)
©
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
![Page 11: Designing APIs for Others](https://reader036.vdocuments.us/reader036/viewer/2022081519/5565e436d8b42a20638b4797/html5/thumbnails/11.jpg)
©
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
![Page 12: Designing APIs for Others](https://reader036.vdocuments.us/reader036/viewer/2022081519/5565e436d8b42a20638b4797/html5/thumbnails/12.jpg)
©
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
![Page 13: Designing APIs for Others](https://reader036.vdocuments.us/reader036/viewer/2022081519/5565e436d8b42a20638b4797/html5/thumbnails/13.jpg)
©
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
![Page 14: Designing APIs for Others](https://reader036.vdocuments.us/reader036/viewer/2022081519/5565e436d8b42a20638b4797/html5/thumbnails/14.jpg)
©
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