Your SlideShare is downloading. ×
Designing APIs for Others
Upcoming SlideShare
Loading in...5

Thanks for flagging this SlideShare!

Oops! An error has occurred.


Saving this for later?

Get the SlideShare app to save on your phone or tablet. Read anywhere, anytime - even offline.

Text the download link to your phone

Standard text messaging rates apply

Designing APIs for Others


Published on

Real World Lessons about Commercial API Development

Real World Lessons about Commercial API Development

Published in: Technology

1 Like
  • Be the first to comment

No Downloads
Total Views
On Slideshare
From Embeds
Number of Embeds
Embeds 0
No embeds

Report content
Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

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
  • Transcript

    • 1. Designing APIs for Others
      Real World Lessons About
      Commercial API Development
    • 2. Typical Programming Goals
      Minimize maintenance cost & risk
      Extensible / refactorable to new requirements
      Easy to read the source code
    • 3. 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
    • 4. How Users Discover
      Code Samples
      Very narrow, taken literally
      IntelliSense Driven Discovery
      See that they probably can do what they want to.
    • 5. 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
    • 6. 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
    • 7. Inheritance
      Awkward IntelliSense
      Hardening Tricky
      Alternating viewpoints (External & Internal)
      Compromise Simplicity
      • Advanced User Cool Factor
      • 8. 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
    • 9. Hardening
      Event Pattern
      Property Transitions
    • 10. 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
    • 11. Packaging
      Fewer Assemblies
      Runnable Sample Solution
      Clear Redistribution Requirements
      Xml Help, PDB if feasible
      Unit tests if available
    • 12. Common Mistakes
      Users aren’t as smart as you
      Domain knowledge
      Coding capability
      Internal / Tribe Language
      Framework + API + Experience
      Single Minded
    • 13. Most Common Mistake
      You must have at least two, independent external teams use your API while it’s still changeable
    • 14. Additional Information
      Framework Design Guidelines by Krzysztof Cwalina
      Follow Up
      Twitter: kendallmiller