Share
Embed

Slide 1

Slide 1 text

! Three simple rules for building an API Ben Balter @benbalter [email protected] 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

! [email protected] doesn’t scale

Slide 35

Slide 35 text

! [email protected] 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 [email protected] government.github.com