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