API Antipatterns - Speaker Deck

Slide 1

Slide 1 text

API Anti Patterns or, how to not f**k up your API

Slide 2

Slide 2 text

API Anti Patterns or, how to not f**k up your API

Slide 3

Slide 3 text

or, tips on how to annoy your API consumers

Slide 4

Slide 4 text

or, think you know REST? Awesome!

Slide 5

Slide 5 text

or, some of the crazy s**t people do with REST

Slide 6

Slide 6 text

Hello

Slide 7

Slide 7 text

Mike Pearce

Slide 8

Slide 8 text

http://social-network.com /MikePearce

Slide 9

Slide 9 text

http://social-network.com /MikeyPearce

Slide 10

Slide 10 text

http://social-network.com /mikepearce.net

Slide 11

Slide 11 text

http://social-network.com /MikePearce

Slide 12

Slide 12 text

An Apology

Slide 13

Slide 13 text

SONISPHERE @ Knebworth Flags should be banned a festivals!

Slide 14

Slide 14 text

Burritos: Best. Festival. Food. Ever.

Slide 15

Slide 15 text

No content

Slide 16

Slide 16 text

Mike, Lee and Rog

Slide 17

Slide 17 text

SORRY

Slide 18

Slide 18 text

( ) HTTP REQUEST: That you get on with it...

Slide 19

Slide 19 text

Why am I here? REST

Slide 20

Slide 20 text

Why am I here? REST

Slide 21

Slide 21 text

Why am I here? REST Hah!

Slide 22

Slide 22 text

Why am I here? REST Huh?! ST

Slide 23

Slide 23 text

Do’s ✔

Slide 24

Slide 24 text

Do’s Dont’s ✔ ✘

Slide 25

Slide 25 text

Do’s Dont’s Whatevs.. ✔ ✘ ☠

Slide 26

Slide 26 text

But first... Some background

Slide 27

Slide 27 text

Who? Roy Fielding (the grandfather)

Slide 28

Slide 28 text

There!

Slide 29

Slide 29 text

Architectural Styles and the Design of Network- based Software Architectures Can’t sleep? Read this...

Slide 30

Slide 30 text

No content

Slide 31

Slide 31 text

A quick primer And now ...

Slide 32

Slide 32 text

REST != HTTP

Slide 33

Slide 33 text

REST != HTTP REST != The Web

Slide 34

Slide 34 text

REST

Slide 35

Slide 35 text

REST IS NOT

Slide 36

Slide 36 text

REST IS NOT HARD

Slide 37

Slide 37 text

REST IS NOT HARD Seriously!

Slide 38

Slide 38 text

Standards? We don’t need no steenkin’ standards!

Slide 39

Slide 39 text

MY CONSTRAINTS, LET ME SHOW YOU THEM

Slide 40

Slide 40 text

Some verbs...

Slide 41

Slide 41 text

Some nouns...

Slide 42

Slide 42 text

GET

Slide 43

Slide 43 text

PINT

Slide 44

Slide 44 text

PINT Please!

Slide 45

Slide 45 text

ANTI patterns Onto the main event

Slide 46

Slide 46 text

Overuse of ...

Slide 47

Slide 47 text

GET

Slide 48

Slide 48 text

No content

Slide 49

Slide 49 text

Overuse of GET and POST or, GET/POST tunnelling.

Slide 50

Slide 50 text

No content

Slide 51

Slide 51 text

No content

Slide 52

Slide 52 text

BAD http://api.ﬂickr.com/services/ rest/?method= ﬂickr.photos.people.add &api_key=nnn&photo_id=yyy&u ser_id=xxx GET:

Slide 53

Slide 53 text

PUT: /user/MikePearce api_key=moo& age=33& size=medium& power=ﬂight GOOD

Slide 54

Slide 54 text

PUT or POST? ASIDE PUT: /users/MikePearce PUT: /links/google PUT: /articles/100805/putorpost

Slide 55

Slide 55 text

PUT or POST? ASIDE POST: /documents/save name=styleguide.css& category=design

Slide 56

Slide 56 text

PUT or POST? ASIDE PUT when the resource will live at the target URI POST when you want the server to handle the location of the resource.

Slide 57

Slide 57 text

POST: /dostuff/ user=MikePearce& action=delete& api_key=moo& token=quack& mode=3 BAD

Slide 58

Slide 58 text

GOOD DELETE: /user/MikePearce Wait! What? Why!?

Slide 59

Slide 59 text

Tunneling Errors through 200 OK?

Slide 60

Slide 60 text

Are you OK? I’m ﬁne! Great! A 200 OK!

Slide 61

Slide 61 text

I’m ﬁne! Are you OK? ARGGHH! He doesn’t understand me! Great! A 200 OK!

Slide 62

Slide 62 text

This is better...

Slide 63

Slide 63 text

GET: /droid/r2d2 GET: /droid/c3po 404: Not the droids you’re looking for

Slide 64

Slide 64 text

HTTP/1.1 200 OK Content-Type: text/plain Error! You have errored. What am I supposed to do with this?

Slide 65

Slide 65 text

RESPONSE CODES Which leads me nicely to...

Slide 66

Slide 66 text

IE has failed Informational

Slide 67

Slide 67 text

Success FTW!1

Slide 68

Slide 68 text

Redirection

Slide 69

Slide 69 text

Client Error (you try illustrating client error!)

Slide 70

Slide 70 text

Server Error It’s 1am. I can’t find an image for server error.

Slide 71

Slide 71 text

HTTP/1.1 200 OK PUT: /user/MikePearce Meh..

Slide 72

Slide 72 text

HTTP/1.1 201 CREATED PUT: /user/MikePearce Huzzah!

Slide 73

Slide 73 text

HTTP/1.1 418 GET: /whatareyou

Slide 74

Slide 74 text

HTTP/1.1 418 I’m a teapot GET: /whatareyou This one is real1!!

Slide 75

Slide 75 text

Caching

Slide 76

Slide 76 text

No content

Slide 77

Slide 77 text

E-Tags

Slide 78

Slide 78 text

HTTP/1.1 304 NOT MODIFIED HTTP/1.1 200 OK Date: Mon, 23 May 2005 22:38:34 GMT Last-Modified: Wed, 08 Jan 2003 23:11:55 Etag: "3f80f-1b6-3e1cb03b" Connection: close Content-Type: text/html; charset=UTF-8

Slide 79

Slide 79 text

Mmm ... Delicious!

Slide 80

Slide 80 text

Slide 81

Slide 81 text

HYPERMEDIA

Slide 82

Slide 82 text

HYPERMEDIA What is it?

Slide 83

Slide 83 text

HYPERMEDIA What is it?

Slide 84

Slide 84 text

HYPERMEDIA AS THE ENGINE OF APPLICATION STATE

Slide 85

Slide 85 text

oar...

Slide 86

Slide 86 text

HATEOAS (Remember hating oars)

Slide 87

Slide 87 text

Grey Areas

Slide 88

Slide 88 text

V3r510n1ng Versioning

Slide 89

Slide 89 text

GET: /user/MikePearce Him again. Prolific bastard.

Slide 90

Slide 90 text

GET: /user/MikePearce GET: /user/66

Slide 91

Slide 91 text

GET: /v1/user/MikePearce 1. Versioning with the URI GET: /v2/user/66

Slide 92

Slide 92 text

GET: /user/66 2. Not versioning the primary URI GET: /v1/user/MikePearce

Slide 93

Slide 93 text

GET: /user/66 3. No versioning

Slide 94

Slide 94 text

Document Extensions

Slide 95

Slide 95 text

Either

Slide 96

Slide 96 text

Either GET: /reports/tpsreport/summary.json GET: /reports/tpsreport/summary.xml

Slide 97

Slide 97 text

Either GET: /reports/tpsreport/summary.json GET: /reports/tpsreport/summary.xml or

Slide 98

Slide 98 text

Either GET: /reports/tpsreport/summary.json GET: /reports/tpsreport/summary.xml or Accept: text/xml Accept: application/json

Slide 99

Slide 99 text

SUM MARY Phew!

Slide 100

Slide 100 text

Overuse of GET and POST or, GET/POST tunnelling.

Slide 101

Slide 101 text

Tunneling Errors through 200 OK?

Slide 102

Slide 102 text

RESPONSE CODES Which leads me nicely to...

Slide 103

Slide 103 text

E-Tags

Slide 104

Slide 104 text

Slide 105

Slide 105 text

HATEOAS (Remember hating oars)

Slide 106

Slide 106 text

V3r510n1ng Versioning

Slide 107

Slide 107 text

Either GET: /reports/tpsreport/summary.json GET: /reports/tpsreport/summary.xml or Accept: text/xml Accept: application/json

Slide 108

Slide 108 text

Any questions? (that I can answer!)

Slide 109

Slide 109 text

Photo Credits Wordle.net flickr.com/photos/wouterkiel/3717057757/ - Wouter Kiel flickr.com/photos/joe_13/19946186/ - joe_13 flickr.com/photos/23846880@N00/391925649/ - Rutger de Moddertukker flickr.com/photos/mararie/264942105/ - mararie flickr.com/photos/ndanger/7841795/ - ndanger flickr.com/photos/yourdon/2573762303/ - Ed Yourdon flickr.com/photos/thunderchild5/225675773/ - Thunderchild7 flickr.com/photos/duchamp/126115989/ - Duchamp flickr.com/photos/thefangmonster/490423135/ - The fang monster flickr.com/photos/nostri-imago/2894328425/ - cliff1066 flickr.com/photos/epsos/4582789354/ - epSos.de flickr.com/photos/projector/2092517108/ - allie pasquier flickr.com/photos/nickstone333/3135320160/ - nickstone333 flickr.com/photos/rdrcollection/116454033/ - Rodney Ramsey flickr.com/photos/christophercarfi/2730304130/ - Christophercarfi flickr.com/photos/turatti/4526352835/ - jaci xIII

Slide 110

Slide 110 text

Mike Pearce [email protected] mikepearce.net twtitter.com/mikepearce Thanks!