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

    View full-size slide

  2. !
    All APIs should be three things

    View full-size slide

  3. !
    APIs should be simple

    View full-size slide

  4. !
    APIs should be semantic

    View full-size slide

  5. !
    APIs should be supported

    View full-size slide

  6. !
    All APIs should be simple

    View full-size slide

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

    View full-size slide

  8. !
    Option 0: scrape opensource.org
    Option 1: scrape spdx.org
    Option 2: parce an excel file

    View full-size slide

  9. !
    Pro-tip: prototype your API

    View full-size slide

  10. !
    choosealicense.com/licenses.json

    View full-size slide

  11. !
    api.github.com/licenses

    View full-size slide

  12. !
    api.github.com/licenses/mit

    View full-size slide

  13. !
    api.github.com/repos/benbalter/gman

    View full-size slide

  14. !
    All APIs should be semantic

    View full-size slide

  15. !
    FDsys is not

    View full-size slide

  16. !
    (Thunder and dramatic music)

    View full-size slide

  17. !
    Web developers love 

    2+ MB XML files

    View full-size slide

  18. !
    Data should be immediately valuable

    View full-size slide

  19. !
    github.com/benbalter/so_far_so_good

    View full-size slide

  20. !
    Data should make sense to computers

    View full-size slide

  21. !
    Data should make sense to humans

    View full-size slide

  22. !
    Data shouldn’t mimic 

    their paper counterparts

    View full-size slide

  23. !
    Data should be reimagined for the web

    View full-size slide

  24. !
    Optimize for developer happiness

    View full-size slide

  25. !
    All APIs should be supported

    View full-size slide

  26. !
    [email protected] is a great way
    to answer the same question
    over and over again

    View full-size slide

  27. !
    Users have (the same) questions

    View full-size slide

  28. !
    The only appropriate way to
    answer a question about your
    API is with a URL

    View full-size slide

  29. !
    Today, the first step to solving
    any problem is to Google it

    View full-size slide

  30. !
    Microsoft has been rocking the
    knowledge base for decades

    View full-size slide

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

    View full-size slide

  32. !
    Bonus #2: 

    Collaborative documentation

    View full-size slide

  33. !
    If you liked it then you should
    have put a URL on it

    View full-size slide

  34. !
    To review…

    View full-size slide

  35. !
    APIs should be simple

    View full-size slide

  36. !
    APIs should be semantic

    View full-size slide

  37. !
    APIs should be supported

    View full-size slide

  38. !
    Three simple rules
    for building an API
    Ben Balter
    @benbalter
    [email protected]
    government.github.com

    View full-size slide