Three simple rules for building APIs

Three simple rules for building APIs

APIs should be simple, semantic, and supported.

19d03ecc1ff5da1a5e63a3ddaa2d84c2?s=128

Ben Balter

March 31, 2015
Tweet

Transcript

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

    @benbalter government@github.com 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. ! data@agency.gov doesn’t scale

  35. ! data@agency.gov 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 government@github.com government.github.com