The document serves as an introduction to RESTful web services, covering HTTP protocol basics, differences between REST and RPC, and best practices for designing RESTful services. It discusses essential concepts such as HTTP methods, responses, caching, authentication, and content negotiation, emphasizing the importance of adhering to REST principles while being pragmatic in implementation. The document also touches on the benefits of REST, including its compatibility with various tools and standards.

1. So you think you know REST?
An introducton to RESTful webservices, HTTP and
best practces.

2. Evert Pot
Engineer @ ibuildings
Interested in Web
infrastructure, api design
and scalability.
Runs the 'SabreDAV' open-
source project.
2

3. The talk
• Short REST introduction
• HTTP protocol basics
• Advanced HTTP features
3

4. Defining REST
4

5. Defining REST
• Coined by Roy Fielding in 2000
• Fielding is one of the HTTP 1.0
and 1.1 authors
• Fielding's dissertation barely
mentions HTTP
5

6. Defining REST
• Amazon S3 api
• AtomPub
• G(oogle)Data
6

7. Defining REST
• REST is an architectural style
• Open to interpretation and
discussion
• Which is not what we're
going to do
7

8. So you think you know REST
8

9. So you think you know REST
9

10. Designing proper RESTful
services in an HTTP context
while respecting the HTTP
protocol design, where it makes
sense.
10

11. REST vs. RPC
11

12. REST vs. RPC
POST /api/?method=editPost&postId=123
POST /api/?method=getPost&postId=123
POST /1/statuses/update.json
12

13. REST vs. RPC
POST /rpc HTTP/1.1
Host: www.example.org
Content-Type: text/xml; charset=utf-8
<?xml version=”1.0”?>
<methodCall>
<methodName>getPhotos</methodName>
<params>
<param>
<value><string>latest</string></value>
</param>
<param>
<value><int>100</int></value>
</param>
</params>
</methodCall>
13

14. REST vs. RPC
HTTP/1.1 200 Ok
Content-Type: text/xml; charset=utf-8
<?xml version=”1.0”?>
<methodResponse>
<params>
<param>
<value>
<array>
<data>
<value><string>photo1.png</string></value>
</data>
</array>
</value>
</param>
</params>
</methodResponse>
14

15. REST vs. RPC
POST /api/?method=getPosts&format=json
POST /api/?method=getPost&postId=123&format=json
POST /api/?method=newPost
POST /api/?method=editPost&postId=123
POST /api/?method=deletePost&postId=123
POST /api/?method=publishPost&postId=123
15

16. REST vs. RPC
POST /api/posts/index.json
POST /api/posts/view/123.json
POST /api/posts/add
POST /api/posts/edit/123
POST /api/posts/delete/123
POST /api/posts/publish/123
16

17. REST vs. RPC
GET /api/posts
GET /api/posts/123
POST /api/posts
PUT /api/posts/123
DELETE /api/posts/123
17

18. Representation
GET /api/posts/123 HTTP/1.1
HTTP/1.1 200 Ok
Content-Type: application/json
{
article : {
title : “hello world”,
body : “...”
}
}
18

19. Representation
PUT /api/posts/123 HTTP/1.1
Content-Type: application/json
{
article : {
title : “hello world, v2”,
body : “...”
}
}
HTTP/1.1 204 No Content
19

20. Representational State Transfer
State Current database state
Representation JSON or XML document
Transfer GET, PUT, etc.
20

21. Benefits of RPC
• A lot of tooling available (SOAP)
• An RPC API might map better to your
existing (internal) api's.
• Easily maps to popular programming
languages.
21

22. Benefits of RESTful design
• Major components are well-defined
and lots or prior art:
– Caching
– Authentication
– Proxies
– Redirection
– Addressability
– Content-negotation
– And so on..
22

23. HTTP!
23

24. HTTP Request
PUT /articles/helloworld HTTP/1.1
Host: blog.example.org
Content-Type: text/html
Content-Length: 40
User-Agent: Hal/9000
<h1>Hello world</h1>
...
24

25. HTTP Response
HTTP/1.1 415 Unsupported Media Type
Content-Type: application/xml
Content-Length: 576
Server: GeorgeForeman/2000
Date: Thu, 18 Nov 2010 16:40:04 GMT
<?xml version=”1.0”?>
<error>
<message>You must submit articles in text/plain
format</message>
</error>
25

26. HTTP methods
CONNECT DELETE
GET HEAD
OPTIONS POST
PUT TRACE
26

27. HTTP methods
ACL LABEL OPTIONS TRACE
BASELINE-CONTROL LINK ORDERPATCH UNBIND
BIND LOCK PATCH UNCHECKOUT
CHECKIN MERGE POST UNLINK
CHECKOUT MKACTIVITY PROPFIND UNLOCK
CONNECT MKCALENDAR PROPPATCH UPDATE
COPY MKCOL PUT UPDATEREDIRECTREF
DELETE MKREDIRECTREF REBIND VERSION-CONTROL
GET MKWORKSPACE REPORT
HEAD MOVE SEARCH
27

28. HTTP methods
ACL LABEL OPTIONS TRACE
BASELINE-CONTROL LINK ORDERPATCH UNBIND
BIND LOCK PATCH UNCHECKOUT
CHECKIN MERGE POST UNLINK
CHECKOUT MKACTIVITY PROPFIND UNLOCK
CONNECT MKCALENDAR PROPPATCH UPDATE
COPY MKCOL PUT UPDATEREDIRECTREF
DELETE MKREDIRECTREF REBIND VERSION-CONTROL
GET MKWORKSPACE REPORT
HEAD MOVE SEARCH
28

29. HTTP GET
• Retrieval
• Safe
• No side-effects
• Idempotent
• Will return “200 Ok” in most cases
29

30. HTTP HEAD
• HEAD = GET – response body
• Safe
• No side-effects
• Idempotent
30

31. HTTP PUT
• Update or create new resource at
specified url
• Not safe
• Idempotent
• Atomic
• Return “200 Ok” or “201 Created”
31

32. HTTP DELETE
• Deletes a resource
• Not safe
• Idempotent
• Atomic
• Return “204 No Content”
32

33. HTTP POST
• Not safe
• Not Idempotent
• Used for RPC and 'everything else'
• Most REST services use this to create
new resources
33

34. Why POST for creation?
PUT /articles HTTP/1.1
Content-Type: text/plain
..new article..
34

35. Why POST for creation?
PUT /articles HTTP/1.1
Content-Type: text/plain
..new article..
• Implies we're replacing /articles
• Not idempotent
35

36. Except
PUT /images/logo.png HTTP/1.1
Content-Type: image/png
PUT /posts/550e8400-e29b-41d4-
a716-446655440000 HTTP/1.1
Content-Type: application/json
36

37. HTTP PATCH
• Brand new (march 2010)
• Used for partial updates, appending,
etc.
• Format is up to you
• Not safe
• Not idempotent
• Not very RESTful
37

38. RESTful principals
• Strive for them
• Don't religiously follow them
38

39. RESTful principals
• Strive for them
• Don't religiously follow them
• Start with a fully RESTful service
• And then add workarounds and
optimizations.
39

40. Responses
Use appropriate HTTP status
codes.
Use the response body for
additional about errors.
40

41. 1xx Informational
100 Continue
101 Switching Protocols
102 Processing
41

42. 2xx Success
200 Ok
201 Created
202 Accepted
203 Non-Authorative Information
204 No Content
205 Partial Content
207 Multi-Status
208 Already Reported
226 IM Used
42

43. 3xx Redirection
300 Multiple Choices
301 Moved Permanently
302 Found
303 See Other
304 Not Modified
305 Use Proxy
307 Temporary Redirect
43

44. 4xx Your Fault
400 Bad Request 413 Request Entity Too Long
401 Unauthorized 414 Request-URI Too Long
402 Payment Required 415 Unsupported Media Type
403 Forbidden 416 Requested Range Not
404 Not Found Satisfiable
405 Method Not Allowed 417 Expectation Failed
407 Proxy Authentication Required 418 I'm a Teapot
408 Request Timeout 422 Unprocessable Entity
409 Conflict 423 Locked
410 Gone 424 Failed Dependency
411 Length Required 426 Upgrade Required
412 Precondition Failed
44

45. 5xx Our Fault
500 Internal Server Error
501 Not Implemented
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout
505 HTTP Version Not Supported
506 Variant Also Negotiates
507 Insufficient Storage
508 Loop Detected
509 Bandwidth Limit Exceeded
510 Not Extended
45

46. Important HTTP features
Caching
Conditional Requests
Content-Negotiation
Authentication
46

47. Caching
GET /articles HTTP/1.1
Host: api.example.org
HTTP/1.1 200 Ok
Cache-Control: private; max-age=3600; must-revalidate
Expires: Thu, 07 Apr 2011 01:30:00 GMT
Last-Modified: Tue, 17 May 2011 04:58:08 GMT
ETag: “e5199316748f31141d21498a29b25a7c”
Pragma: no-cache
Content-Type: text/html
..Content..
47

48. Caching
GET /foo GET /foo
Varnish Apache
200 200
Ok Ok
48

49. Caching
GET /foo GET /foo
Varnish Apache
200 200
Ok Ok
GET /foo
Varnish Apache
200
Ok
49

50. Caching
GET /articles HTTP/1.1
Host: api.example.org
If-None-Match: “e5199316748f31141d21498a29b25a7c”
If-Modified-Since: Tue, 17 May 2011 04:58:08 GMT
HTTP/1.1 304 Not Modified
Cache-Control: private; max-age=3600; must-revalidate
Expires: Thu, 07 Apr 2011 01:30:00 GMT
Last-Modified: Tue, 17 May 2011 04:58:08 GMT
ETag: “e5199316748f31141d21498a29b25a7c”
Note: If-None-Match & If-Modified-Since should not both appear in a request
50

51. Conditional Requests
• Ensuring you're not overwriting
others' changes.
PUT /articles/123 HTTP/1.1
Host: api.example.org
If-Match: “e5199316748f31141d21498a29b25a7c”
If-Unmodified-Since: Tue, 17 May 2011 04:58:08 GMT
HTTP/1.1 412 Precondition Failed
Etag: “ac05a877f0043790da4a7d9672b0d4a9”
51

52. Conditional Requests
• Only create resources if they didn't
already exist
PUT /images/logo.png HTTP/1.1
Host: api.example.org
If-Match: *
HTTP/1.1 412 Precondition Failed
52

53. ETag vs Last-Modified
• ETag is just string-matching
• Dates allows for ranges
– But often not correctly implemented
• Dates are harder to parse
• Dates are only accurate per-second
53

54. Content-Negotiation
• Any resource may have multiple
representations
• A client may prefer a specific
representation
• Multiple representations may include
different languages, different file
formats, encodings, etc.
54

55. Content-Negotiation
GET /articles/123 HTTP/1.1
Accept: text/html, application/atom+xml
Accept-Encoding: gzip
Accept-Language: nl, en-GB, en, *
Accept-Charset: utf-8
HTTP/1.1 200 Ok
Content-Type: text/html; charset=utf-8
Content-Encoding: gzip
Content-Language: nl-BE
55

56. Content-Negotiation
Bad
GET /articles/123.json?lang=nl HTTP/1.1
Good
GET /articles/123 HTTP/1.1
Accept-Language: nl, en-GB, *
Accept: application/json
Accept-Encoding: gzip
Accept-Charset: utf-8
56

57. Although..
GET /foo GET /foo
Varnish Apache
200 200
Ok Ok
57

58. Although..
GET /foo GET /foo
Varnish Apache
200 200
Ok Ok
GET /foo
Varnish Apache
200 Ok
58

59. Although..
GET /foo GET /foo
Varnish Apache
200 200
Ok Ok
GET /foo
Varnish Apache
200 Ok
59

60. The Vary: header
Vary: tells caches there may be
variations in responses.
HTTP/1.1 200 Ok
Content-Type: text/html; charset=utf-8
Content-Encoding: gzip
Content-Language: nl-NL
Vary: Accept-Language
60

61. Authentication
61

62. Authentication
Common schemes:
• Basic
• Digest
• OAuth
62

63. Authentication - Basic
• Very easy to implement
• Widely supported
• Very insecure without SSL
• Password not hashed
base64(username + ':' + password)
63

64. Authentication - Digest
• Widely supported
• Password is hashed
• Replay attack protection
• Decent MiTM protection
• Possibly increased roundtrips
A1=md5(username:realm:password)
A2=md5(request-method:request-uri)
Digest=md5(A1:nonce:nc:cnonce:qop:A2)
64

65. Authentication - OAuth
• Popular for public API's
• Now an RFC standard
• Complicated for
consumers
• No full protection against
replay attacks
• Moving target
65

66. OAuth 3-legged auth
Service
Provider
User Consumer
66

67. OAuth 2-legged auth
Service
• Same API Provider
• Less authentication
steps
Resist the temptation
Consumer
67

68. Authentication
Basic Digest OAuth
Mitm Terrible Decent Decent
protection
Password None Salted hash HMAC
encryption
Ease of use Very Good Challenging
Browser Yes Yes No
support
Increased No Possibly No
roundtrips
68

69. Authentication
Basic Digest OAuth
Mitm Great Great Great
protection
Password Encrypted, Great Great
encryption not hashed
Ease of use Very Good Challenging
Browser Yes Yes No
support
Increased No Possibly No
roundtrips
69

70. Conclusion (1/2)
REST is good for you, because:
• You can use a ton of software as-is
• You don't have to reinvent the wheel
• It's future compatible
70

71. Conclusion (2/2)
If you're implementing a REST service
• Be pragmatic
• Use standards where appropriate
• Have no shame in using a sub- or
superset of the standards.
71

72. Thank you!
@evertp
http://joind.in/3231
72