Designing APIs for Others

Designing APIs for Others
Real World Lessons About
Commercial API Development

Typical Programming Goals
Minimize maintenance cost & risk
Extensible / refactorable to new requirements
Easy to read the source code

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

How Users Discover
Code Samples
Very narrow, taken literally
IntelliSense Driven Discovery
See that they probably can do what they want to.

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

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

Inheritance
Awkward IntelliSense
Hardening Tricky
Alternating viewpoints (External & Internal)
Compromise Simplicity
Advanced User Cool Factor
Customer Request Safety Net

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

Hardening
Event Pattern
Property Transitions
Inheritance

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

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

Common Mistakes
Users aren’t as smart as you
Domain knowledge
Coding capability
Internal / Tribe Language
Inconsistent
Framework + API + Experience
Single Minded

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

Additional Information
Book
Framework Design Guidelines by Krzysztof Cwalina
Websites
www.GibraltarSoftware.com
www.eSymmetrix.com
Follow Up
Kendall.Miller@eSymmetrix.com
Twitter: kendallmiller

http://reliable.esymmetrix.com	408
http://rocksolid.gibraltarsoftware.com	88
http://kendall.srellim.org	11
http://translate.googleusercontent.com	6
http://webcache.googleusercontent.com	1

Designing APIs for Others

by Gibraltar Software on Oct 10, 2010

Accessibility

Categories

Tags

Upload Details

Usage Rights

5 Embeds 514

Statistics

Designing APIs for Others — Presentation Transcript