Three simple rules for building APIs

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

! All APIs should be three things

! APIs should be simple

! APIs should be semantic

! APIs should be supported

! All APIs should be simple

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

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

! Pro-tip: prototype your API

! choosealicense.com/licenses.json

! Meh.

! api.github.com/licenses

! api.github.com/licenses/mit

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

! All APIs should be semantic

! FDsys is not

! The FAR

! (Thunder and dramatic music)

! Web developers love   2+ MB XML files

! Data should be immediately valuable

! github.com/benbalter/so_far_so_good

! Data should make sense to computers

! Data should make sense to humans

! Data shouldn’t mimic   their paper counterparts

! Data should be reimagined for the web

! Optimize for developer happiness

! All APIs should be supported

! [email protected] doesn’t scale

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

! Users have (the same) questions

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

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

! Microsoft has been rocking the knowledge base for decades

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

! Bonus #2:   Collaborative documentation

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

! To review…

! APIs should be simple

! APIs should be semantic

! APIs should be supported

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

More Decks by Ben Balter