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 identifies 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)
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/filter/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/?filter=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 Conflict
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
first 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 notification 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
• Identification 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 workflow 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 difficult
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 fine
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 Lovefilm 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 defined 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
• Difficult 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 profit!
• 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 efficiency. 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-workflow
• Roy Thomas Fielding
Architectural Styles and the Design of Network-based Software
Architectures
http://www.ics.uci.edu/~fielding/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:
[email protected]