Link
Embed
Share
Beginning
This slide
Copy link URL
Copy link URL
Copy iframe embed code
Copy iframe embed code
Copy javascript embed code
Copy javascript embed code
Share
Tweet
Share
Tweet
Slide 1
Slide 1 text
! Three simple rules for building an API Ben Balter @benbalter government@github.com government.github.com
Slide 2
Slide 2 text
! All APIs should be three things
Slide 3
Slide 3 text
! APIs should be simple
Slide 4
Slide 4 text
! APIs should be semantic
Slide 5
Slide 5 text
! APIs should be supported
Slide 6
Slide 6 text
! All APIs should be simple
Slide 7
Slide 7 text
! Let’s say you want a list of open source licenses…
Slide 8
Slide 8 text
! Option 0: scrape opensource.org Option 1: scrape spdx.org Option 2: parce an excel file
Slide 9
Slide 9 text
! Pro-tip: prototype your API
Slide 10
Slide 10 text
! choosealicense.com/licenses.json
Slide 11
Slide 11 text
! Meh.
Slide 12
Slide 12 text
! api.github.com/licenses
Slide 13
Slide 13 text
No content
Slide 14
Slide 14 text
! api.github.com/licenses/mit
Slide 15
Slide 15 text
No content
Slide 16
Slide 16 text
! api.github.com/repos/benbalter/gman
Slide 17
Slide 17 text
No content
Slide 18
Slide 18 text
! All APIs should be semantic
Slide 19
Slide 19 text
! FDsys is not
Slide 20
Slide 20 text
! The FAR
Slide 21
Slide 21 text
! (Thunder and dramatic music)
Slide 22
Slide 22 text
No content
Slide 23
Slide 23 text
! Web developers love 2+ MB XML files
Slide 24
Slide 24 text
! Data should be immediately valuable
Slide 25
Slide 25 text
! github.com/benbalter/so_far_so_good
Slide 26
Slide 26 text
! Data should make sense to computers
Slide 27
Slide 27 text
No content
Slide 28
Slide 28 text
! Data should make sense to humans
Slide 29
Slide 29 text
No content
Slide 30
Slide 30 text
! Data shouldn’t mimic their paper counterparts
Slide 31
Slide 31 text
! Data should be reimagined for the web
Slide 32
Slide 32 text
! Optimize for developer happiness
Slide 33
Slide 33 text
! All APIs should be supported
Slide 34
Slide 34 text
! data@agency.gov doesn’t scale
Slide 35
Slide 35 text
! data@agency.gov is a great way to answer the same question over and over again
Slide 36
Slide 36 text
! Users have (the same) questions
Slide 37
Slide 37 text
! The only appropriate way to answer a question about your API is with a URL
Slide 38
Slide 38 text
! Today, the first step to solving any problem is to Google it
Slide 39
Slide 39 text
! Microsoft has been rocking the knowledge base for decades
Slide 40
Slide 40 text
! Bonus #1: Your community will answer its own questions
Slide 41
Slide 41 text
No content
Slide 42
Slide 42 text
! Bonus #2: Collaborative documentation
Slide 43
Slide 43 text
No content
Slide 44
Slide 44 text
No content
Slide 45
Slide 45 text
! If you liked it then you should have put a URL on it
Slide 46
Slide 46 text
! To review…
Slide 47
Slide 47 text
! APIs should be simple
Slide 48
Slide 48 text
! APIs should be semantic
Slide 49
Slide 49 text
! APIs should be supported
Slide 50
Slide 50 text
! Three simple rules for building an API Ben Balter @benbalter government@github.com government.github.com