Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Three simple rules for building APIs

Three simple rules for building APIs

APIs should be simple, semantic, and supported.

Ben Balter

March 31, 2015
Tweet

More Decks by Ben Balter

Other Decks in Technology

Transcript

  1. ! Three simple rules for building an API Ben Balter

    @benbalter [email protected] government.github.com
  2. ! All APIs should be three things

  3. ! APIs should be simple

  4. ! APIs should be semantic

  5. ! APIs should be supported

  6. ! All APIs should be simple

  7. ! Let’s say you want a list of open source

    licenses…
  8. ! Option 0: scrape opensource.org Option 1: scrape spdx.org Option

    2: parce an excel file
  9. ! Pro-tip: prototype your API

  10. ! choosealicense.com/licenses.json

  11. ! Meh.

  12. ! api.github.com/licenses

  13. None
  14. ! api.github.com/licenses/mit

  15. None
  16. ! api.github.com/repos/benbalter/gman

  17. None
  18. ! All APIs should be semantic

  19. ! FDsys is not

  20. ! The FAR

  21. ! (Thunder and dramatic music)

  22. None
  23. ! Web developers love 
 2+ MB XML files

  24. ! Data should be immediately valuable

  25. ! github.com/benbalter/so_far_so_good

  26. ! Data should make sense to computers

  27. None
  28. ! Data should make sense to humans

  29. None
  30. ! Data shouldn’t mimic 
 their paper counterparts

  31. ! Data should be reimagined for the web

  32. ! Optimize for developer happiness

  33. ! All APIs should be supported

  34. ! [email protected] doesn’t scale

  35. ! [email protected] is a great way to answer the same

    question over and over again
  36. ! Users have (the same) questions

  37. ! The only appropriate way to answer a question about

    your API is with a URL
  38. ! Today, the first step to solving any problem is

    to Google it
  39. ! Microsoft has been rocking the knowledge base for decades

  40. ! Bonus #1: Your community will answer its own questions

  41. None
  42. ! Bonus #2: 
 Collaborative documentation

  43. None
  44. None
  45. ! If you liked it then you should have put

    a URL on it
  46. ! To review…

  47. ! APIs should be simple

  48. ! APIs should be semantic

  49. ! APIs should be supported

  50. ! Three simple rules for building an API Ben Balter

    @benbalter [email protected] government.github.com