Designing for Others- Commercial API Design (NYC Code Camp)

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.

IntelliSense Discovery Demo

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 Demo

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

Hardening Demo

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.

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

Designing for Others- Commercial API Design (NYC Code Camp)

by Gibraltar Software on Feb 28, 2011

Accessibility

Categories

Upload Details

Usage Rights

1 Embed 106

Statistics

Designing for Others- Commercial API Design (NYC Code Camp) — Presentation Transcript