TrustArc Webinar - Unlock the Power of AI-Driven Data Discovery
Designing APIs for Others
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 Designer->Compile->Runtime
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 Consistency
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 Inconsistent 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 Book Framework Design Guidelines by Krzysztof Cwalina Websites www.GibraltarSoftware.com www.eSymmetrix.com Follow Up Kendall.Miller@eSymmetrix.com Twitter: kendallmiller
Notas do Editor
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
