Slide 1

Slide 1 text

DESIGNING HTTP INTERFACES AND RESTFUL WEB SERVICES

Slide 2

Slide 2 text

David Zuelke

Slide 3

Slide 3 text

David Zülke

Slide 4

Slide 4 text

http://en.wikipedia.org/wiki/File:München_Panorama.JPG

Slide 5

Slide 5 text

Founder

Slide 6

Slide 6 text

No content

Slide 7

Slide 7 text

No content

Slide 8

Slide 8 text

@dzuelke

Slide 9

Slide 9 text

THE OLDEN DAYS Before REST was En Vogue

Slide 10

Slide 10 text

http://www.acme.com/index.php?action=zomg&page=lol

Slide 11

Slide 11 text

along came

Slide 12

Slide 12 text

 dis is srs SEO bsns

Slide 13

Slide 13 text

and said

Slide 14

Slide 14 text

NEIN NEIN NEIN NEIN DAS IST VERBOTEN

Slide 15

Slide 15 text

at least if they were

Slide 16

Slide 16 text

No content

Slide 17

Slide 17 text

so we had to make URLs "SEO friendly"

Slide 18

Slide 18 text

http://www.acme.com/zomg/lol

Slide 19

Slide 19 text

and then things got out of control

Slide 20

Slide 20 text

because nobody really had a clue

Slide 21

Slide 21 text

http://acme.com/videos/latest/hamburgers

Slide 22

Slide 22 text

http://acme.com/search/lolcats/pictures/yes/1/200

Slide 23

Slide 23 text

oh dear…

Slide 24

Slide 24 text

THE RISE OF WEB SERVICES Ohai, I'm ur CEO, I canhaz SOAP API plz, today, kthx?

Slide 25

Slide 25 text

POST /soapendpoint.php HTTP/1.1 Host: localhost Content-‐Type: text/xml; charset=utf-‐8 123456 HTTP/1.1 200 OK Content-‐Type: text/xml; charset=utf-‐8 123456 Red Stapler 3.14

Slide 26

Slide 26 text

POST /soapendpoint.php HTTP/1.1 Host: localhost Content-‐Type: text/xml; charset=utf-‐8 987654 HTTP/1.1 500 Internal Service Error Content-‐Type: text/xml; charset=utf-‐8 SOAP-‐ENV:Server Unknown Product

Slide 27

Slide 27 text

SOAP sucks, said everyone

Slide 28

Slide 28 text

let's build APIs without the clutter, they said

Slide 29

Slide 29 text

example: the http://joind.in/ API

Slide 30

Slide 30 text

POST /api/talk HTTP/1.1 Host: joind.in Content-‐Type: text/xml; charset=utf-‐8 Chuck Norris roundhousekick 42 HTTP/1.1 200 OK Content-‐Type: text/xml; charset=utf-‐8 My Test Talk This is a sample talk description 42

Slide 31

Slide 31 text

PROBLEMS WITH THIS API • Always a POST • Doesn't use HTTP Authentication • Operation information is enclosed in the request ("getdetail") • Nothing there is cacheable • Everything through one endpoint (/api/talks for talks)

Slide 32

Slide 32 text

Level 0 in the Richardson Maturity Model: Plain old XML over the wire in an RPC fashion

Slide 33

Slide 33 text

Room for improvement: use one URI for each resource “ “

Slide 34

Slide 34 text

That would be Level 1 in Richardson's Maturity Model

Slide 35

Slide 35 text

Level 0 and Level 1 are a bag of hurt. Do not use them. Ever.

Slide 36

Slide 36 text

ALONG CAME ROY FIELDING And Gave Us REST

Slide 37

Slide 37 text

that was awesome

Slide 38

Slide 38 text

because everyone could say

Slide 39

Slide 39 text

 I haz REST nao

Slide 40

Slide 40 text

when in fact

Slide 41

Slide 41 text

they bloody didn’t

Slide 42

Slide 42 text

REST What Does That Even Mean?

Slide 43

Slide 43 text

REpresentational State Transfer

Slide 44

Slide 44 text

Roy Thomas Fielding: Architectural styles and the design of network based software architectures.

Slide 45

Slide 45 text

• Client-Server • Stateless • Cacheable • Layered System • Code on Demand (optional) • Uniform Interface REST CONSTRAINTS

Slide 46

Slide 46 text

• A URL identiﬁes a Resource • Methods perform operations on resources • The operation is implicit and not part of the URL • A hypermedia format is used to represent the data • Link relations are used to navigate a service UNIFORM INTERFACE

Slide 47

Slide 47 text

a web page is not a resource

Slide 48

Slide 48 text

it is a (complete) representation of a resource

Slide 49

Slide 49 text

GET /products/ HTTP/1.1 Host: acme.com Accept: application/json HTTP/1.1 200 OK Content-‐Type: application/json; charset=utf-‐8 Allow: GET, POST [ { id: 1234, name: "Red Stapler", price: 3.14, location: "http://acme.com/products/1234" } ] GETTING JSON BACK

Slide 50

Slide 50 text

GET /products/ HTTP/1.1 Host: acme.com Accept: application/xml HTTP/1.1 200 OK Content-‐Type: application/xml; charset=utf-‐8 Allow: GET, POST Red Stapler 3.14 GETTING XML BACK

Slide 51

Slide 51 text

but those are not hypermedia formats!

Slide 52

Slide 52 text

(more on that a bit later)

Slide 53

Slide 53 text

GET /products/ HTTP/1.1 Host: acme.com Accept: application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,*/*;q=0.5 User-‐Agent: Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_5_8; en-‐us) AppleWebKit… HTTP/1.1 200 OK Content-‐Type: text/html; charset=utf-‐8 Allow: GET, POST ACME Inc. Products

Our Incredible Products

Red Stapler (€3.14)

AND FINALLY, HTML

Slide 54

Slide 54 text

VOLUME ONE Designing an HTTP Interface

Slide 55

Slide 55 text

FIRST: DEFINE RESOURCES A Good Approach: Structure Your URLs

Slide 56

Slide 56 text

BAD URLS • http://www.acme.com/product/ • http://www.acme.com/product/ﬁlter/cats/desc • http://www.acme.com/product/1234 • http://www.acme.com/photos/product/1234 • http://www.acme.com/photos/product/1234/new • http://www.acme.com/photos/product/1234/5678 WTF? photo or product ID? new what?

Slide 57

Slide 57 text

GOOD URLS • http://www.acme.com/products/ • http://www.acme.com/products/?ﬁlter=cats&sort=desc • http://www.acme.com/products/1234 • http://www.acme.com/products/1234/photos/ • http://www.acme.com/products/1234/photos/?sort=latest • http://www.acme.com/products/1234/photos/5678 a list of products filtering is a query a single product all photos

Slide 58

Slide 58 text

now here's the ironic part

Slide 59

Slide 59 text

URLs don't matter once you have a fully RESTful interface

Slide 60

Slide 60 text

but it’s helpful to think in terms of resources

Slide 61

Slide 61 text

SECOND: USE RESOURCES CRUD, but not really

Slide 62

Slide 62 text

COLLECTION OPERATIONS • http://www.acme.com/products/ • GET to retrieve a list of products • POST to create a new product • returns • 201 Created • Location: http://www.acme.com/products/1235

Slide 63

Slide 63 text

ITEM OPERATIONS • http://www.acme.com/products/1234 • GET to retrieve • PUT to update • DELETE to, you guessed it, delete

Slide 64

Slide 64 text

and remember

Slide 65

Slide 65 text

don't let the server maintain client state (e.g. cookies)

Slide 66

Slide 66 text

Now we are at Level 2 in RMM

Slide 67

Slide 67 text

RMM LEVEL 2 • Use HTTP verbs • GET (safe and idempotent) • POST (unsafe, not idempotent) • PUT & DELETE (unsafe, idempotent) • Use HTTP status codes to indicate result success • e.g. HTTP/1.1 409 Conﬂict

Slide 68

Slide 68 text

THE TWITTER API Not RESTful, And Not Even Getting HTTP Right :(

Slide 69

Slide 69 text

mind you we're not even inspecting the RESTfulness

Slide 70

Slide 70 text

we're just looking at Twitter's API from an HTTP perspective

Slide 71

Slide 71 text

• GET http://api.twitter.com/1/statuses/show/12345.json • Problems: • Operation (“show”) included in the URL • Status ID not a child of the “statuses” collection • Better: GET http://twitter.com/statuses/12345 with Accept header STATUSES/SHOW

Slide 72

Slide 72 text

• POST http://api.twitter.com/1/statuses/update.json • Problems: • Operation (“update”) included in the URL • Uses the authenticated user implicitly • Better: POST http://twitter.com/users/fabpot/statuses/ STATUSES/UPDATE

Slide 73

Slide 73 text

• POST http://api.twitter.com/1/statuses/destroy/12345.json • Problems: • Operation (“destroy”) included in the URL like it’s 1997 • Odd, illogical hierarchy again • Allows both “POST” and “DELETE” as verbs • Better: DELETE http://twitter.com/statuses/12345 STATUSES/DESTROY

Slide 74

Slide 74 text

• GET http://api.twitter.com/1/statuses/retweets/12345.json • Problems: • Hierarchy is wrong • Better: GET http://twitter.com/statuses/12345/retweets/ STATUSES/RETWEETS

Slide 75

Slide 75 text

• PUT http://api.twitter.com/1/statuses/retweet/12345.format • Problems: • “retweets” collection exists, but is not used here • As usual, the action is in the URL (“make retweet” is RPC-y) • Allows both “PUT” and “POST” as verbs • Better: POST http://twitter.com/statuses/12345/retweets/ STATUSES/RETWEET

Slide 76

Slide 76 text

SUMMARY • http://twitter.com/statuses/ • POST to create a new tweet • http://twitter.com/statuses/12345 • DELETE deletes (PUT could be used for updates) • http://twitter.com/statuses/12345/retweets/ • POST creates a new retweet

Slide 77

Slide 77 text

INTERMISSION What's the Biggest Reason for the Success of the Web?

Slide 78

Slide 78 text

WWW

Slide 79

Slide 79 text

ﬁrst data exchange system

Slide 80

Slide 80 text

planetary scale

Slide 81

Slide 81 text

No content

Slide 82

Slide 82 text

No content

Slide 83

Slide 83 text

why is that possible?

Slide 84

Slide 84 text

Hyperlinks!

Slide 85

Slide 85 text

no tight coupling!

Slide 86

Slide 86 text

loosely coupled by design

Slide 87

Slide 87 text

no notiﬁcation infrastructure

Slide 88

Slide 88 text

HTTP/1.1 404 Not Found

Slide 89

Slide 89 text

embraces failure

Slide 90

Slide 90 text

more information != more friction

Slide 91

Slide 91 text

no limits to scalability

Slide 92

Slide 92 text

WWW is protocol-centric

Slide 93

Slide 93 text

VOLUME TWO RESTful Services with Hypermedia

Slide 94

Slide 94 text

THE UNIFORM INTERFACE • Identiﬁcation of Resources (e.g. through URIs) • Representations are conceptually separate! • Manipulation Through Representations (i.e. they are complete) • Self-Descriptive Messages (containing all information) • Hypermedia As The Engine Of Application State ("HATEOAS") magic awesomesauce essential to REST

Slide 95

Slide 95 text

HATEOAS The Missing Piece in the Puzzle

Slide 96

Slide 96 text

ONE LAST PIECE IS MISSING • How does a client know what to do with representations? • How do you go to the “next” operation? • What are the URLs for creating subordinate resources? • Where is the contract for the service?

Slide 97

Slide 97 text

HYPERMEDIA AS THE ENGINE OF APPLICATION STATE • Use links to allow clients to discover locations and operations • Link relations are used to express the possible options • Clients do not need to know URLs, so they can change • The entire application workﬂow is abstracted, thus changeable • The hypermedia type itself could be versioned if necessary • No breaking of clients if the implementation is updated!

Slide 98

Slide 98 text

(X)HTML and Atom are Hypermedia formats

Slide 99

Slide 99 text

Or you roll your own...

Slide 100

Slide 100 text

GET /products/1234 HTTP/1.1 Host: acme.com Accept: application/vnd.com.acme.shop+xml HTTP/1.1 200 OK Content-‐Type: application/vnd.come.acme.shop+xml; charset=utf-‐8 Allow: GET, PUT, DELETE 1234 Red Stapler 3.14 re-use Atom for link relations meaning defined in IANA Link Relations list A CUSTOM MEDIA TYPE Remind clients of Uniform Interface :)

Slide 101

Slide 101 text

boom, RMM Level 3

Slide 102

Slide 102 text

XML is really good for hypermedia formats

Slide 103

Slide 103 text

(hyperlinks, namespaced attributes, re-use of formats, …)

Slide 104

Slide 104 text

JSON is more difﬁcult

Slide 105

Slide 105 text

(no hyperlinks, no namespaces, no element attributes)

Slide 106

Slide 106 text

1234 Red Stapler 3.14 { id: 1234, name: "Red Stapler", price: { amount: 3.14, currency: "EUR" }, links: [ { rel: "payment", type: "application/vnd.com.acme.shop+json", href: "http://acme.com/products/1234/payment" } ] } XML VERSUS JSON

Slide 107

Slide 107 text

also, JSON is hard to evolve without breaking clients

Slide 108

Slide 108 text

Bacon 5.99

Slide 109

Slide 109 text

Bacon 5.99 OMNOMNOM Bacon

Slide 110

Slide 110 text

Bacon 5.99 4.49

Slide 111

Slide 111 text

Bacon Speck 5.99

Slide 112

Slide 112 text

Bacon Speck 5.99

Slide 113

Slide 113 text

and hey

Slide 114

Slide 114 text

without hypermedia, your HTTP interface is not RESTful

Slide 115

Slide 115 text

that’s totally ﬁne and sometimes even the only way to do it

Slide 116

Slide 116 text

(e.g. CouchDB or S3 are never going to be RESTful)

Slide 117

Slide 117 text

just avoid calling it a "REST API" :)

Slide 118

Slide 118 text

good hypermedia format example: the Loveﬁlm API

Slide 119

Slide 119 text

6 1 1 true 2003-‐09-‐12 http://openapi.lovefilm.com/catalog/title/59643 false 574 4

Slide 120

Slide 120 text

ROOM FOR IMPROVEMENT IN THE LOVEFILM API • Uses application/xml instead of a custom media type • Once that is fixed, all the link elements could also have a “type” attribute indicating the media type • Should use XML namespaces on the root element, with one namespace per type (e.g. “urn:com.lovefilm.api.item”, “urn:com.lovefilm.api.searchresult” and so on) • That way, clients can determine the resource type easily

Slide 121

Slide 121 text

another great RESTful API: Huddle

Slide 122

Slide 122 text

19475 98 2007-‐10-‐10T09:02:17Z 2011-‐10-‐10T09:02:17Z Complete 9

Slide 123

Slide 123 text

ROOM FOR IMPROVEMENT IN THE HUDDLE API • Uses custom rels like “thumb” or “avatar” not deﬁned in the IANA registry (http://www.iana.org/assignments/link-relations) • Risk of collisions and ambiguity; should use something like “http://rels.huddle.net/thumb” instead. • Uses one global XML schema and namespace for all entities • Clients cannot detect entity type based on namespace • Difﬁcult to evolve schema versions independently

Slide 124

Slide 124 text

API VERSIONING Media Types To The Rescue!

Slide 125

Slide 125 text

why not api.myservice.com/v1/foo/bar? and then api.myservice.com/v2/foo/bar?

Slide 126

Slide 126 text

different URLs means different resources!

Slide 127

Slide 127 text

also, keep bookmarks (by machines) in mind

Slide 128

Slide 128 text

GET /products HTTP/1.1 Host: acme.com Accept: application/vnd.com.myservice+xml HTTP/1.1 200 OK Content-‐Type: application/vnd.com.myservice+xml; charset=utf-‐8 Allow: GET, POST Red Stapler 3.14 API VERSION 1

Slide 129

Slide 129 text

(some years pass...)

Slide 130

Slide 130 text

GET /products HTTP/1.1 Host: acme.com Accept: application/vnd.com.myservice.v2+xml HTTP/1.1 200 OK Content-‐Type: application/vnd.com.myservice.v2+xml; charset=utf-‐8 Allow: GET, POST Red Stapler 3.14 false API VERSION 2

Slide 131

Slide 131 text

clients can’t upgrade protocol for known URLs!

Slide 132

Slide 132 text

Also, imagine every install of phpBB or TYPO3 had an API

Slide 133

Slide 133 text

If the version is in the URL, clients need to regex those

Slide 134

Slide 134 text

http://sharksforum.org/community/api/v1/threads/102152

Slide 135

Slide 135 text

http://forum.sharksforum.org/api/v1/threads/102152

Slide 136

Slide 136 text

that would be fail

Slide 137

Slide 137 text

or what if another forum software wants the same API?

Slide 138

Slide 138 text

also would have to use “/v1/” in their URLs

Slide 139

Slide 139 text

URI based versioning kills interoperability

Slide 140

Slide 140 text

YOU MIGHT BE WONDERING Why Exactly Is This Awesome?

Slide 141

Slide 141 text

THE MERITS OF REST • Easy to evolve: add new features or elements without breaking BC • Easy to learn: developers can "browse" service via link rels • Easy to scale up: grows well with number of features, users and servers • Easy to implement: build it on top of HTTP, and proﬁt! • Authentication & TLS • Caching & Load Balancing • Conditional Requests • Content Negotiation

Slide 142

Slide 142 text

but...

Slide 143

Slide 143 text

hold on, you say

Slide 144

Slide 144 text

a plain HTTP-loving service does the job, you say

Slide 145

Slide 145 text

surely, there is a merit to REST beyond extensibility, you ask

Slide 146

Slide 146 text

nope

Slide 147

Slide 147 text

"REST is software design on the scale of decades: every detail is intended to promote software longevity and independent evolution. Many of the constraints are directly opposed to short-term efﬁciency. Unfortunately, people are fairly good at short-term design, and usually awful at long-term design." Roy Fielding

Slide 148

Slide 148 text

"Most of REST's constraints are focused on preserving independent evolvability over time, which is only measurable on the scale of years. Most developers simply don't care what happens to their product years after it is deployed, or at least they expect to be around to rewrite it when such change occurs." Roy Fielding

Slide 149

Slide 149 text

FURTHER READING • Ryan Tomayko How I Explained REST to my Wife http://tomayko.com/writings/rest-to-my-wife • Jim Webber, Savas Parastatidis & Ian Robinson How to GET a Cup of Coffee http://www.infoq.com/articles/webber-rest-workﬂow • Roy Thomas Fielding Architectural Styles and the Design of Network-based Software Architectures http://www.ics.uci.edu/~ﬁelding/pubs/dissertation/top.htm

Slide 150

Slide 150 text

BOOKS ON REST • Jim Webber, Savas Parastatidis, Ian Robinson REST in Practice ISBN: 978-0596805821 • Subbu Allamaraju RESTful Web Services Cookbook ISBN: 978-0596801687 • Leonard Richardson, Sam Ruby RESTful Web Services ISBN: 978-0596529260

Slide 151

Slide 151 text

!e End

Slide 152

Slide 152 text

Questions?

Slide 153

Slide 153 text

THANK YOU! This was http://joind.in/6590 by @dzuelke Send me questions or hire us: david.zuelke@bitextender.com