Familiarity Breeds Contempt (Or why all APIs suck, even yours.)
0 likes•2,491 views
The document discusses the common shortcomings of APIs, emphasizing that poor API design leads to poor applications. It highlights the importance of documentation, error handling, and considering user needs when creating APIs. The author urges developers to avoid easy criticism and instead focus on creating functional and user-friendly interfaces.
Familiarity Breeds Contempt (Or why all APIs suck, even yours.)
- 1. Familiarity Breeds Contempt Or why all APIs suck. Even yours. Stephen Darlington @sdarlington / @wandlesoftware www.wandlesoftware.com / www.zx81.org.uk
- 2. After using Facebook Connect
- 3. After using the Twitter API By Makuahine Pa'i Ki'i
- 4. After using your API By VFW Kids
- 5. After using your API By Lara604
- 6. What is an API? • “An application programming interface, or API, is the set of symbols that are exported and available to the users of a library to write their application.” (The Little Manual of API Design) • “The design of the APIs is arguably the most critical part of designing the library”
- 7. What is an API? • An interface used to communicate with people – Web service API – A reusable Cocoa component – List of functions in a header file • “Other people” includes the “future you”
- 8. It’s easy to be a critic “In many ways, the work of a critic is easy. We risk very little, yet enjoy a position over those who offer up their work and their selves to our judgment. We thrive on negative criticism, which is fun to write and to read.” Anton Ego, Food critic, Ratatouille
- 9. Using it • Documentation • Complete • Error handling
- 10. Using it – example • Adding a bookmark in Delicious.com • https://api.delicious.com/v1/posts/add – url – description – extended – tags – shared
- 11. Using it – example • Error – “Something went wrong” • OK – “done” • But: – URL might have changed – Huge GET request
- 12. Using it • Documentation • Complete • Error handling • Mobile considerations
- 13. Using it – example 2 • Syncing Delicious.com bookmarks • https://api.delicious.com/v1/posts/all – hashes= • https://api.delicious.com/v1/posts/get – meta=yes – hashes=
- 14. Using it – example 2 • You have to download all the “hashes” – How many? – How big? • “hashes” means different things in different commands • Very long GET request • Undocumented parameters
- 15. Changing it • Documentation • Versions • Compatibility • Notice period
- 16. Let’s try to be positive… • Don’t think “what’s the easiest way of making all this data public?” – Consider use-cases of clients • Give it a REST – Leave religion to the church. Make it work first • Use your own API – Don’t have “secret” methods – Amazon are a great example
- 17. Conclusions • Terrible APIs == Terrible Apps • Don’t short-change yourself • Don’t short-change your users
- 18. Further Reading • “The Little Manual of API Design,” Jasmin Blanchette • “ API Design,” Matt Gemmell
- 19. More?! • Questions? • Apps and slides at wandlesoftware.com
Editor's Notes
- #4: She’s sad, and yet she has a burger, too.
- #6: No, but really…
- #7: If changing it might cause someone pain, it’s pretty much an API for the purposes of this talk
- #8: If changing it might cause someone pain, it’s pretty much an API for the purposes of this talk
- #10: Documentation Coming soon. Link to partial. Inadequate to code against No example. Complete Crap syncing Think about your use cases Error handling "something went wrong” (delicious) Facebook API fails when no friends GameCenter mysteriously fails when one user is connected on Simulator rather than a real device
- #12: Consistent way of accessing data. Example: when you add a URL, the URL that gets saved is not always the one you send (you’ve mentioned stripping out some of the Google Reader junk; Delicious “helpfully” converts “www.wandlesoftware.com” to “http://www.wandlesoftware.com”). The only way to have the offline copy up-to-date is by doing a complete sync again. Tags is with commas… which they changed without any notice and without changing the rest of the API.
- #13: Mobile considerations: Limited memory Limited bandwidth Potentially high latency Unreliable Really bad proxy servers
- #14: You need the = after “hashes”
- #15: If you want to allow syncing… why not have a “changes since DATE” function? Allow “get all” but in “pages”
- #16: Versions Upward compatibility Spaces vs commas use same version Adding new features, but keeping the same version (and not documenting it) Notice period Yahoo ID Twitter oauth
- #17: The title of this talk is “Familiarity Breeds Contempt” for a reason. You need to *use* an API to really appreciate it – and almost anything you’ve used you find problems with. That doesn’t mean they’re all bad – it’s a spectrum – but you should aim to be at the right end of the spectrum.
- #18: Or at least, apps that are not as good as they could have been. The time I spend battling the API could have been better spent making the UI better or adding more features.