Designing APIs for Others<br />Real World Lessons About <br />Commercial API Development<br />
Typical Programming Goals<br />Minimize maintenance cost & risk<br />Extensible / refactorable to new requirements<br />Ea...
Commercial API Goals<br />Other people use your library and like it.<br />Short First Reference -> First Wow<br />Digestib...
How Users Discover<br />Code Samples<br />Very narrow, taken literally<br />IntelliSense Driven Discovery<br />See that th...
IntelliSense Discovery Demo<br />
Design Priorities<br />Discovery through your fingers<br />Where possible can’t be misused<br />Don’t show what they don’t...
Key Implementation Method<br />Always outside in – terms, flow, exception types.<br />Reads like the outline of a book<br ...
Inheritance Demo<br />
Inheritance<br />Awkward IntelliSense<br />Hardening Tricky<br />Alternating viewpoints (External & Internal)<br />Comprom...
Customer Request Safety Net</li></li></ul><li>Exceptions<br />Thrown at very predictable points<br />Use intrinsic types w...
Hardening<br />Event  Pattern<br />Property Transitions<br />Inheritance<br />
Hardening Demo<br />
FxCop / VS Code Analysis<br />Catches all manner of subtle things<br />You can ignore its advice – but know why<br />Use o...
Packaging<br />Fewer Assemblies<br />Runnable Sample Solution<br />Clear Redistribution Requirements<br />Xml Help, PDB if...
Common Mistakes<br />Users aren’t as smart as you<br />Domain knowledge<br />Coding capability<br />Internal / Tribe Langu...
Most Common Mistake<br />You must have at least two, independent external teams use your API while it’s still changeable<b...
Additional Information<br />Book<br />Framework Design Guidelines by Krzysztof Cwalina<br />Websites<br />www.GibraltarSof...
Upcoming SlideShare
Loading in …5
×

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

1,255 views

Published on

Published in: Technology
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
1,255
On SlideShare
0
From Embeds
0
Number of Embeds
140
Actions
Shares
0
Downloads
8
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide
  • Your biggest competition is the user’s belief in the difficulty of solving the problem.
  • Misuse prevention: Thread safety, order of operations, types, null behaviorsDon’t show what they don’t need: Internal, hide on interfaces, veneer the APIHard Shell: Don’t trust any code around or above you.
  • Consistent with the framework and itself, then with likely customer experience.
  • Prefer to have the fewest assemblies you can, and their names are part of their interface.Use different names for valid combinations – like .NET 20 and .NET 40. Have a reason for the CUSTOMER that you broke apart
  • Your job is to hide the complexity of your domain from users, not show how smart you areQuality is tightly related to how well it blends into the enviornmentYour preferences aren’t their preferences – configuration, designer or code
  • Designing for Others- Commercial API Design (NYC Code Camp)

    1. 1. Designing APIs for Others<br />Real World Lessons About <br />Commercial API Development<br />
    2. 2. Typical Programming Goals<br />Minimize maintenance cost & risk<br />Extensible / refactorable to new requirements<br />Easy to read the source code<br />
    3. 3. Commercial API Goals<br />Other people use your library and like it.<br />Short First Reference -> First Wow<br />Digestible, iterative discovery<br />Easy Things are Easy, Hard Things are Possible<br />
    4. 4. How Users Discover<br />Code Samples<br />Very narrow, taken literally<br />IntelliSense Driven Discovery<br />See that they probably can do what they want to.<br />
    5. 5. IntelliSense Discovery Demo<br />
    6. 6. Design Priorities<br />Discovery through your fingers<br />Where possible can’t be misused<br />Don’t show what they don’t need<br />Advanced features in advanced ways<br />Hard Shell<br />Designer->Compile->Runtime<br />
    7. 7. Key Implementation Method<br />Always outside in – terms, flow, exception types.<br />Reads like the outline of a book<br />Fewer, Flatter<br />Sample Driven Development<br />Samples are your test cases<br />Digestible chunks of WHY<br />Consistency<br />
    8. 8. Inheritance Demo<br />
    9. 9. Inheritance<br />Awkward IntelliSense<br />Hardening Tricky<br />Alternating viewpoints (External & Internal)<br />Compromise Simplicity<br /><ul><li>Advanced User Cool Factor
    10. 10. Customer Request Safety Net</li></li></ul><li>Exceptions<br />Thrown at very predictable points<br />Use intrinsic types wherever they can fit<br />Pick types that make sense from the outside<br />Custom types are great for internal exceptions caught & re-thrown<br />
    11. 11. Hardening<br />Event Pattern<br />Property Transitions<br />Inheritance<br />
    12. 12. Hardening Demo<br />
    13. 13. FxCop / VS Code Analysis<br />Catches all manner of subtle things<br />You can ignore its advice – but know why<br />Use of generic event handlers<br />Exposing generic collections<br />Samples too – don’t require users to break the rules<br />FxCop free in the Windows SDK, VS Code Analysis in Pro & higher editions.<br />
    14. 14. Packaging<br />Fewer Assemblies<br />Runnable Sample Solution<br />Clear Redistribution Requirements<br />Xml Help, PDB if feasible<br />Unit tests if available<br />
    15. 15. Common Mistakes<br />Users aren’t as smart as you<br />Domain knowledge<br />Coding capability<br />Internal / Tribe Language<br />Inconsistent<br />Framework + API + Experience<br />Single Minded<br />
    16. 16. Most Common Mistake<br />You must have at least two, independent external teams use your API while it’s still changeable<br />
    17. 17. Additional Information<br />Book<br />Framework Design Guidelines by Krzysztof Cwalina<br />Websites<br />www.GibraltarSoftware.com<br />www.eSymmetrix.com<br />Follow Up<br />Kendall.Miller@eSymmetrix.com<br />Twitter: kendallmiller<br />

    ×