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.

3

The talk

• Short REST introduction• HTTP protocol basics• Advanced HTTP features

4

Defining REST

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

6

Defining REST

• Amazon S3 api• AtomPub• G(oogle)Data

7

Defining REST

• REST is an architectural style• Open to interpretation and

discussion• Which is not what we're

going to do

8

So you think you know REST

9

So you think you know REST

10

Designing proper RESTfulservices in an HTTP context while respecting the HTTP

protocol design, where it makes sense.

11

REST vs. RPC

12

REST vs. RPC

POST /api/?method=editPost&postId=123

POST /api/?method=getPost&postId=123

POST /1/statuses/update.json

13

REST vs. RPCPOST /rpc HTTP/1.1Host: www.example.orgContent-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>

14

REST vs. RPCHTTP/1.1 200 OkContent-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>

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

16

REST vs. RPC

POST /api/posts/index.jsonPOST /api/posts/view/123.jsonPOST /api/posts/addPOST /api/posts/edit/123POST /api/posts/delete/123POST /api/posts/publish/123

17

REST vs. RPC

GET /api/posts

GET /api/posts/123

POST /api/posts

PUT /api/posts/123

DELETE /api/posts/123

18

Representation

GET /api/posts/123 HTTP/1.1

HTTP/1.1 200 OkContent-Type: application/json

{ article : { title : “hello world”, body : “...” }}

19

Representation

PUT /api/posts/123 HTTP/1.1Content-Type: application/json

{ article : { title : “hello world, v2”, body : “...” }}

HTTP/1.1 204 No Content

20

State Current database state

Representation JSON or XML document

Transfer GET, PUT, etc.

Representational State Transfer

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.

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..

23

HTTP!

24

HTTP Request

PUT /articles/helloworld HTTP/1.1Host: blog.example.orgContent-Type: text/htmlContent-Length: 40User-Agent: Hal/9000

<h1>Hello world</h1>

...

25

HTTP Response

HTTP/1.1 415 Unsupported Media TypeContent-Type: application/xmlContent-Length: 576Server: GeorgeForeman/2000Date: Thu, 18 Nov 2010 16:40:04 GMT

<?xml version=”1.0”?><error> <message>You must submit articles in text/plain format</message></error>

26

HTTP methods

CONNECT DELETE

GET HEAD

OPTIONS POST

PUT TRACE

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

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

29

HTTP GET

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

30

HTTP HEAD

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

31

HTTP PUT

• Update or create new resource at specified url

• Not safe• Idempotent• Atomic• Return “200 Ok” or “201 Created”

32

HTTP DELETE

• Deletes a resource• Not safe• Idempotent• Atomic• Return “204 No Content”

33

HTTP POST

• Not safe• Not Idempotent• Used for RPC and 'everything else'• Most REST services use this to create

new resources

34

Why POST for creation?

PUT /articles HTTP/1.1Content-Type: text/plain

..new article..

35

Why POST for creation?

PUT /articles HTTP/1.1Content-Type: text/plain

..new article..

• Implies we're replacing /articles• Not idempotent

36

Except

PUT /images/logo.png HTTP/1.1Content-Type: image/png

PUT /posts/550e8400-e29b-41d4-a716-446655440000 HTTP/1.1Content-Type: application/json

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

38

RESTful principals

• Strive for them• Don't religiously follow them

39

RESTful principals

• Strive for them• Don't religiously follow them

• Start with a fully RESTful service• And then add workarounds and

optimizations.

40

Responses

Use appropriate HTTP status codes.

Use the response body for additional about errors.

41

1xx Informational

100 Continue101 Switching Protocols102 Processing

42

2xx Success

200 Ok201 Created202 Accepted203 Non-Authorative Information204 No Content205 Partial Content207 Multi-Status208 Already Reported226 IM Used

43

3xx Redirection

300 Multiple Choices301 Moved Permanently302 Found303 See Other304 Not Modified305 Use Proxy307 Temporary Redirect

44

4xx Your Fault400 Bad Request

401 Unauthorized

402 Payment Required

403 Forbidden

404 Not Found

405 Method Not Allowed

407 Proxy Authentication Required

408 Request Timeout

409 Conflict

410 Gone

411 Length Required

412 Precondition Failed

413 Request Entity Too Long

414 Request-URI Too Long

415 Unsupported Media Type

416 Requested Range Not Satisfiable

417 Expectation Failed

418 I'm a Teapot

422 Unprocessable Entity

423 Locked

424 Failed Dependency

426 Upgrade Required

45

5xx Our Fault

500 Internal Server Error501 Not Implemented502 Bad Gateway503 Service Unavailable504 Gateway Timeout505 HTTP Version Not Supported506 Variant Also Negotiates507 Insufficient Storage508 Loop Detected509 Bandwidth Limit Exceeded510 Not Extended

46

Important HTTP features

CachingConditional RequestsContent-NegotiationAuthentication

47

Caching

GET /articles HTTP/1.1Host: api.example.org

HTTP/1.1 200 OkCache-Control: private; max-age=3600; must-revalidateExpires: Thu, 07 Apr 2011 01:30:00 GMTLast-Modified: Tue, 17 May 2011 04:58:08 GMTETag: “e5199316748f31141d21498a29b25a7c”Pragma: no-cacheContent-Type: text/html

..Content..

48

Caching

Varnish Apache

GET /foo GET /foo

200 Ok

200 Ok

49

Caching

Varnish Apache

GET /foo GET /foo

200 Ok

200 Ok

Varnish Apache

GET /foo

200 Ok

50

Caching

GET /articles HTTP/1.1Host: api.example.orgIf-None-Match: “e5199316748f31141d21498a29b25a7c”If-Modified-Since: Tue, 17 May 2011 04:58:08 GMT

HTTP/1.1 304 Not ModifiedCache-Control: private; max-age=3600; must-revalidateExpires: Thu, 07 Apr 2011 01:30:00 GMTLast-Modified: Tue, 17 May 2011 04:58:08 GMTETag: “e5199316748f31141d21498a29b25a7c”

Note: If-None-Match & If-Modified-Since should not both appear in a request

51

Conditional Requests

PUT /articles/123 HTTP/1.1Host: api.example.orgIf-Match: “e5199316748f31141d21498a29b25a7c”If-Unmodified-Since: Tue, 17 May 2011 04:58:08 GMT

HTTP/1.1 412 Precondition FailedEtag: “ac05a877f0043790da4a7d9672b0d4a9”

• Ensuring you're not overwriting others' changes.

52

Conditional Requests

PUT /images/logo.png HTTP/1.1Host: api.example.orgIf-Match: *

HTTP/1.1 412 Precondition Failed

• Only create resources if they didn't already exist

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

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.

55

Content-Negotiation

GET /articles/123 HTTP/1.1Accept: text/html, application/atom+xmlAccept-Encoding: gzipAccept-Language: nl, en-GB, en, *Accept-Charset: utf-8

HTTP/1.1 200 OkContent-Type: text/html; charset=utf-8Content-Encoding: gzipContent-Language: nl-BE

56

Content-Negotiation

Bad

GET /articles/123.json?lang=nl HTTP/1.1

Good

GET /articles/123 HTTP/1.1Accept-Language: nl, en-GB, *Accept: application/jsonAccept-Encoding: gzipAccept-Charset: utf-8

57

Although..

Varnish Apache

GET /foo GET /foo

200 Ok

200 Ok

58

Although..

Varnish Apache

GET /foo GET /foo

200 Ok

200 Ok

Varnish Apache

GET /foo

200 Ok

59

Although..

Varnish Apache

GET /foo GET /foo

200 Ok

200 Ok

Varnish Apache

200 Ok

GET /foo

60

The Vary: header

HTTP/1.1 200 OkContent-Type: text/html; charset=utf-8Content-Encoding: gzipContent-Language: nl-NLVary: Accept-Language

Vary: tells caches there may be variations in responses.

61

Authentication

62

Authentication

Common schemes:

• Basic• Digest• OAuth

63

Authentication - Basic

• Very easy to implement• Widely supported• Very insecure without SSL• Password not hashed

base64(username + ':' + password)

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)

65

Authentication - OAuth

• Popular for public API's• Now an RFC standard• Complicated for

consumers• No full protection against

replay attacks• Moving target

66

OAuth 3-legged auth

User Consumer

Service Provider

67

OAuth 2-legged auth

• Same API• Less authentication

steps

Resist the temptation

Consumer

Service Provider

68

Authentication

Basic Digest OAuth

Mitm protection

Terrible Decent Decent

Password encryption

None Salted hash HMAC

Ease of use Very Good Challenging

Browser support

Yes Yes No

Increased roundtrips

No Possibly No

69

Authentication

Basic Digest OAuth

Mitm protection

Great Great Great

Password encryption

Encrypted, not hashed

Great Great

Ease of use Very Good Challenging

Browser support

Yes Yes No

Increased roundtrips

No Possibly No

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

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.

72

Thank you!

@evertp

http://joind.in/3231