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
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
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
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
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
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
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
65. Authentication - OAuth
• Popular for public API's
• Now an RFC standard
• Complicated for
consumers
• No full protection against
replay attacks
• Moving target
65
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