Tweet
Tweet

Slide 1

Slide 1 text

Human First API Design Monday, October 6, 14

Slide 2

Slide 2 text

@motdotla Monday, October 6, 14

Slide 3

Slide 3 text

What is an API? Monday, October 6, 14

Slide 4

Slide 4 text

Application Programming Interface Generically Monday, October 6, 14

Slide 5

Slide 5 text

A set of programming instructions for accessing a Web-based software application. Colloquially Monday, October 6, 14

Slide 6

Slide 6 text

https://api.twitter.com/ 1.1/search/tweets.json? q=USC In Practice Monday, October 6, 14

Slide 7

Slide 7 text

History of APIs Monday, October 6, 14

Slide 8

Slide 8 text

1990s Monday, October 6, 14

Slide 9

Slide 9 text

In the beginning, there was not the web. It’s the year 1990 and it has not yet come about. Sir Tim Berners-Lee has not yet given it to us. Monday, October 6, 14

Slide 10

Slide 10 text

By Christmas 1990, Sir Tim Berners-Lee had given us HTTP, HTML, and the first web browser (named WorldWideWeb). Monday, October 6, 14

Slide 11

Slide 11 text

First API! * GET request and HTML response. * Human friendly. Monday, October 6, 14

Slide 12

Slide 12 text

Browser Wars Monday, October 6, 14

Slide 13

Slide 13 text

WorldWideWeb Mosaic Netscape Internet Explorer Monday, October 6, 14

Slide 14

Slide 14 text

More than HTML. Images, JavaScript, CSS, and more. Monday, October 6, 14

Slide 15

Slide 15 text

Roaring 2000 Monday, October 6, 14

Slide 16

Slide 16 text

Startup empires are built. Ebay, PayPal, Salesforce, and many other giants come out of the late 1990s and the year 2000. Monday, October 6, 14

Slide 17

Slide 17 text

Depression Monday, October 6, 14

Slide 18

Slide 18 text

The bubble bursts. Enter the API. Monday, October 6, 14

Slide 19

Slide 19 text

BizDev 2.0 February 7th, 2000. Salesforce. November 20th, 2000. Ebay. Monday, October 6, 14

Slide 20

Slide 20 text

APIs are wild. No accepted rules. Monday, October 6, 14

Slide 21

Slide 21 text

SOAP Monday, October 6, 14

Slide 22

Slide 22 text

SOAP rises to the forefront as a standard - by Microsoft and the W3C. Monday, October 6, 14

Slide 23

Slide 23 text

UNREST Monday, October 6, 14

Slide 24

Slide 24 text

The rule of SOAP causes problems. It leads to an inflation of code. The cost to fuel one’s application becomes prohibitive. Bugs pile up, todos pile up in long lines. There just isn’t enough resources to offset the problems SOAP introduces. Monday, October 6, 14

Slide 25

Slide 25 text

Incidentally, there are still people living in those SOAP days. I weep for them. Monday, October 6, 14

Slide 26

Slide 26 text

REST Monday, October 6, 14

Slide 27

Slide 27 text

Roy Fielding Monday, October 6, 14

Slide 28

Slide 28 text

Dissertation: “Architectural Styles and the Design of Network-based Software Architectures”. Monday, October 6, 14

Slide 29

Slide 29 text

Removes the ‘UN’ from ‘UNREST’ Monday, October 6, 14

Slide 30

Slide 30 text

Renaissance Monday, October 6, 14

Slide 31

Slide 31 text

Creativity unleashed. Developers create APIs quickly, and mashups from there. Monday, October 6, 14

Slide 32

Slide 32 text

2005. Programmable Web. Monday, October 6, 14

Slide 33

Slide 33 text

2006. Ruby on Rails. Popularizes REST. Monday, October 6, 14

Slide 34

Slide 34 text

API first companies like Twilio & SendGrid thrive. They generally follow REST principles with a tinge of pragmatism. This leads to useful and beautiful things. Monday, October 6, 14

Slide 35

Slide 35 text

The developer is loved during this time. The focus is the developer - not machines. Monday, October 6, 14

Slide 36

Slide 36 text

Progress Monday, October 6, 14

Slide 37

Slide 37 text

New empires are built. But slowly REST loses it’s focus on the developer - on the human. Monday, October 6, 14

Slide 38

Slide 38 text

REST becomes increasingly cold and complex. Monday, October 6, 14

Slide 39

Slide 39 text

Use the correct verb. Monday, October 6, 14

Slide 40

Slide 40 text

New verbs are introduced like PATCH and HEAD. Monday, October 6, 14

Slide 41

Slide 41 text

Complex OAuth authentication becomes the accepted dogma for authenticating an API. Monday, October 6, 14

Slide 42

Slide 42 text

Strict status code usage. Monday, October 6, 14

Slide 43

Slide 43 text

Settings in the headers. Monday, October 6, 14

Slide 44

Slide 44 text

Hypermedia is introduced - adding more complexity. Monday, October 6, 14

Slide 45

Slide 45 text

People preach the REST way and scorn alternative thinking. Monday, October 6, 14

Slide 46

Slide 46 text

The focus is shifting to the machine, and humans are being left out in the cold. Monday, October 6, 14

Slide 47

Slide 47 text

A Heretical Approach: Human First API Design Monday, October 6, 14

Slide 48

Slide 48 text

Guiding Beliefs Monday, October 6, 14

Slide 49

Slide 49 text

Easy as a URL. Monday, October 6, 14

Slide 50

Slide 50 text

https://carte-api.herokuapp.com/api/v0/accounts/ create.json?email=[email]&api_key=[api_key] Monday, October 6, 14

Slide 51

Slide 51 text

Authorization key in the URL. Monday, October 6, 14

Slide 52

Slide 52 text

/accounts/create.json? api_key=[api_key]&email=[ email] Monday, October 6, 14

Slide 53

Slide 53 text

Verb (action) in the URL. Monday, October 6, 14

Slide 54

Slide 54 text

/accounts/create.json? api_key=[api_key]&email=[ email] Monday, October 6, 14

Slide 55

Slide 55 text

Allow for POST body instead of URL. Monday, October 6, 14

Slide 56

Slide 56 text

curl -X POST \ /accounts/create.json \ -d“api_key=[api_key]” \ -d “email=[email] Monday, October 6, 14

Slide 57

Slide 57 text

Any verb. Monday, October 6, 14

Slide 58

Slide 58 text

GET POST *any Monday, October 6, 14

Slide 59

Slide 59 text

There are three things a developer wants to know. Did it work, did I mess up, or did the service mess up. Start with those three - 200, 400, and 500. Get more granular as necessary. Monday, October 6, 14

Slide 60

Slide 60 text

200 400 500 Monday, October 6, 14

Slide 61

Slide 61 text

Output should be JSON and probably recommended format as json:api. Monday, October 6, 14

Slide 62

Slide 62 text

Monday, October 6, 14

Slide 63

Slide 63 text

Human First Examples Monday, October 6, 14

Slide 64

Slide 64 text

Monday, October 6, 14

Slide 65

Slide 65 text

https://api.sendgrid.com/api/mail.send.json? api_user=[api_user]& api_key=[api_key]& to=[to]& from=[from]& subject=[subject]& text=[text] Monday, October 6, 14

Slide 66

Slide 66 text

Monday, October 6, 14

Slide 67

Slide 67 text

Monday, October 6, 14

Slide 68

Slide 68 text

https://api.digitalocean.com/v1/droplets/new? client_id=[client_id]& api_key=[api_key]& name=[droplet_name]& size_id=[size_id]& image_id=[image_id]& region_id=[region_id]&ssh_key_ids= [ssh_key_id1],[ssh_key_id2] Monday, October 6, 14

Slide 69

Slide 69 text

Monday, October 6, 14

Slide 70

Slide 70 text

Next time you build an API consider if you should design it for humans first. Monday, October 6, 14

Slide 71

Slide 71 text

Resources • http://jsonapi.org/ • http://history.apievangelist.com/ • http://money.howstuffworks.com/business-communications/how-to-leverage- an-api-for-conferencing1.htm • https://sendgrid.com • https://digitalocean.com Monday, October 6, 14

Slide 72

Slide 72 text

Thanks Monday, October 6, 14