REST and other important stuff

Representational
State
Transfer
(REST)
(and some other important stuff)
woensdag 25 april 12

View Slide

Warning before we start
‣ REST != MVC
‣ Do not think in controllers, id’s,
actions, models, views, plugins,
helpers etc...
‣ In fact, do not think about
implementation AT ALL!!

View Slide

What is REST?
REST is a coordinated set of architectural constraints that attempts to minimize
latency and network communication while at the same time maximizing the
independence and scalability of component implementations. This is achieved by
placing constraints on connector semantics where other styles have focused on
component semantics. REST enables the caching and reuse of interactions,
dynamic substitutability of components, and processing of actions by
intermediaries, thereby meeting the needs of an Internet-scale distributed
hypermedia system.
Roy Fielding said:

View Slide

What is REST?
‣ ADVANTAGES OF REST
‣ Cacheable
‣ Stateless
‣ Scalable
‣ Fault-tolerant
‣ Loosely coupled

View Slide

What is REST?
‣ URL identiﬁes a resource
‣ URLs have an hierarchy
‣ Methods perform operations on resources
‣ Operation must be implicit
‣ Hypermedia format to represent data
‣ Link relations to navigate
‣ THE PRINCIPLES OF REST

View Slide

What is REST?
‣ THE FOUR MAIN PRINCIPLES
‣ Identiﬁcation of resources
‣ Manipulation of resources
‣ Self-descriptive messages
‣ HATEOAS

View Slide

Identiﬁcation of resources
‣ /index.php?action=getarticle&id=5
‣ /default/article/5/4/6/size
‣ You are doing it wrong... :(
Cacheable? Scalable? Readable?

View Slide

‣ /articles
‣ /articles/5/photos/4/comments/1
‣ /articles/5/photos/4/comments
We want the first comment of the fourth photo for the fifth article
We want all comments of the fourth photo for the fifth article
We want all articles
Cacheable! Scalable! Readable!
‣ Readable and maintainable!

View Slide

✗ /photos/order/size/limit/5
✗ /photos/limit/5/order/size
✓ /photos?order=size&limit=5
✓ /photos?limit=5&order=size
‣ FILTERING THROUGH A QUERY STRING, NOT THE URI

View Slide

What is REST?
‣ HATEOAS

View Slide

Manipulation of resources
‣ Create
‣ Retrieve
‣ Update
‣ Delete
‣ But please note that REST != CRUD

View Slide

‣ Create = PUT
‣ Retrieve = GET
‣ Update = POST
‣ Delete = DELETE
‣ CRUD to HTTP verb mapping

View Slide

‣ SAFE METHODS
‣ Any client should be able to make
the request as many times as
necessary.
‣ GET, OPTIONS, HEAD

View Slide

‣ IDEMPOTENT METHODS
‣ Garantuees that the client can
repeat the request when it’s not
certain.
‣ $x++ vs $x=4
‣ ALL METHODS EXCEPT “POST”

View Slide

What is REST?
‣ HATEOAS

View Slide

Self-descriptive messages
‣ Stateless!
‣ All information for processing is available:
‣ How? (method + content-type)
‣ What? (URI)
‣ When? (preconditions)
‣ Who? (authentication)

View Slide

GET /article/1234 HTTP/1.1
Host: www.enrise.com
Accept: application/vnd.enrise.nl+xml ; version: 1.0
Authorization: OAuth oauth_nonce=”123” ...
If-None-Matched: absad12412414
‣ HOW (method)

View Slide

‣ HOW (content-type)

View Slide

‣ WHAT

View Slide

‣ WHEN

View Slide

‣ WHO

View Slide

What is REST?
‣ HATEOAS

View Slide

HATEOAS
HATEOAS
=
Hypermedia As The Engine Of Application State

View Slide

HATEOAS
This is the hardest and
of course, most important part of REST

View Slide

HATEOAS
‣ Use links to allow clients to discover
locations and operations.
‣ Link relations are used to express
options.
‣ Clients do not need to know URLs.
‣ This controls the state.

View Slide

State inside your REST API
‣ “Flight booking API”
Select Confirm Pay
Fetch
E-Ticket

View Slide

‣ Search for speciﬁed ﬂights
POST /search?order=price&limit=5 HTTP/1.1

LPA
24-may-2011
firstclass


View Slide

‣ Returns a collection of ﬂights
HTTP/1.1 200 OK
Content-type: application/vnd.enrise.nl+xml ; version: 1.0

KL1234
4:24

HV123
3:54


View Slide

‣ Confirm a specific flight
POST /confirm/flight/15263 HTTP/1.1

2A
vegetarian

HTTP/1.1 401 Authentication required

View Slide

‣ Confirm a specific flight, with more info
POST /confirm/flight/15263 HTTP/1.1
Authorization: OAuth ......

2A
vegetarian

HTTP/1.1 200 OK
Location: /booking/1616163


View Slide

‣ What can we do with our booking?
OPTIONS /booking/1616163 HTTP/1.1
HTTP/1.1 200 OK
Allow: GET, DELETE, PUT

View Slide

‣ Cancel our booking!
DELETE /booking/1616163 HTTP/1.1
HTTP/1.1 204 No content

View Slide

‣ Still need to pay for the ﬂight
GET /booking/1616163 HTTP/1.1
Authorization: OAuth...
HTTP/1.1 200 OK

KL1234
4:24

Not paid


View Slide

‣ Pay through another resource
PUT /payment/booking/1616163 HTTP/1.1

4111-1111-1111-1111
04/13
Joshua Thijssen
414.00

HTTP/1.1 201 Created
Location: /payment/booking/1616163

View Slide

‣ Can’t delete our booking since it’s paid
OPTIONS /booking/1616163 HTTP/1.1
HTTP/1.1 200 OK
Allow: GET

View Slide

‣ We can fetch our eticket now
GET /booking/1616163 HTTP/1.1
Authorization: OAuth...
HTTP/1.1 200 OK

KL1234
4:24

Paid in full


View Slide

(Common) pitfalls of REST design
‣ Versioning
‣ Methods in uri
‣ One uri per resource
‣ Controller resources
& non-CRUD

View Slide

‣ Versioning
‣ Methods in uri
‣ Controller resources & Non-CRUD

View Slide

‣ /api/v1.1/article/1234/photos
‣ /api/v1.2/article/1234/photos
‣ Different resources?
‣ Versioning

View Slide

GET /api/article/1234/photos HTTP/1.1
Accept: application/vnd.enrise.nl+xml ; version = 1.0
Accept: application/vnd.enrise.nl+json ; version = 1.1
‣ Versioning
Accept: application/vnd.enrise.nl+json ; version = 5.0.4a

View Slide

‣ Versioning
‣ Methods in uri

View Slide

‣ /api/get/articles/1234/photos
‣ /api/articles/new
‣ /api/articles/list
‣ Methods in URL

View Slide

‣ Versioning
‣ Methods in uri

View Slide

‣ /api/article/1234
‣ /api/article/red+teddybear
‣ Different resources
‣ One URI per resource

View Slide

GET /api/article/red+teddybear HTTP/1.1
HTTP/1.1 303 See Other
Location: /api/article/1234
‣ One URI per resource

View Slide

‣ Versioning
‣ Methods in uri

View Slide

‣ Outside the CRUD?
‣ Multiple operations simultaneously?
‣ Controller resources & non-crud

View Slide

POST /distance HTTP/1.1
Accept: text/xml
Content-type: text/xml;charset=UTF-8

Amersfoort, NLD
Apeldoorn, NLD

HTTP/1.1 200 OK
Content-length: 123
Content-type: text/xml

45
27.96

GET /distance?from=...&to=.. HTTP/1.1
Accept: text/xml

View Slide

POST /user/jthijssen/address_merge HTTP/1.1
Content-type: text/csv;charset=UTF-8
John Doe, 1 Main Street, Seattle, WA
Jane Doe, 100 North Street, Los Angeles, CA
Location: /user/jthijssen/addressbook

View Slide

More important stuff
‣ HTTP Status codes
‣ ETags

View Slide

HTTP Status codes
‣ Status codes are important
‣ They represent the result of your
actions

View Slide

HTTP Status codes
‣ 1xx
‣ 2xx
‣ 3xx
‣ 4xx
‣ 5xx
Informational
Success
Redirection
Client error
Server error

View Slide

HTTP Status codes
‣ 200 OK
‣ 201 Created
‣ 204 No content
‣ IMPORTANT 2xx CODES
Resource returned
Resource created
Resource deleted

View Slide

HTTP Status codes
‣ 304 Not modiﬁed
Resource wasn’t changed

View Slide

HTTP Status codes
‣ 400 Bad request
‣ 401 Unauthorized
‣ 403 Forbidden
‣ 404 Not found
Resource was not found
Not authorized to operate
Not authorized to operate
Incorrect payload

View Slide

HTTP Status codes
‣ 405 Method not allowed
‣ 406 Not acceptable
‣ 412 Precondition failed
Method incorrect
“ETag mismatch”
Cannot return in correct format

View Slide

HTTP Status codes
‣ 500 Internal server error
‣ 501 Not implemented
“Something” happened
Method is not implemented

View Slide

HTTP Status codes
‣ 501 Not implemented vs
405 Method not allowed
‣ 409 Conﬂict vs
412 Precondition failed
‣ de·bat·a·ble/diˈbātəbəl/Adjective

View Slide

ETags & Optimistic locking
GET /blogpost/12345 HTTP/1.1
HTTP/1.1 200 OK
Content-length: 1234000
Content-type: text/xml
ETag: abcd-1234

Joshua Thijssen
...
....


View Slide

GET /blogpost/12345 HTTP/1.1
If-None-Match: abcd-1234
HTTP/1.1 304 Not modified
Blogpost is cached and can be used!

View Slide

POST /blogpost/12345 HTTP/1.1
If-Match: abcd-1234

Sjors de Valk

HTTP/1.1 412 Precondition failed
Blogpost is already modiﬁed by “someone”

View Slide

REST examples
Other REST Examples

View Slide

REST examples
‣ Creating a resource
PUT /articles HTTP/1.1
Content-type: application/vnd.enrise.nl+xml ; version = 1.0

Teddybear
red
15
15,95
19,95

HTTP/1.1 201 Created
Location: /articles/1234

View Slide

REST examples
‣ Getting a resource collection
GET /articles HTTP/1.1
HTTP/1.1 200 OK
Content-type: application/vnd.enrise.nl+xml
Date: sun, 01 Nov 2010 12:34:56 GMT

Teddybear

Skippyball


View Slide

REST examples
‣ Getting a resource
GET /articles/1234 HTTP/1.1
HTTP/1.1 200 OK
Content-type: application/vnd.enrise.nl+xml
Date: sun, 01 Nov 2010 12:34:56 GMT

Teddybear
...

HTTP/1.1 404 Not found
Content-length: 0
Date: sun, 01 Nov 2010 12:34:56 GMT

View Slide

REST examples
‣ Delete a resource
DELETE /articles/1234 HTTP/1.1
HTTP/1.1 204 No content
Content-length: 0
Date: sun, 01 Nov 2010 12:34:56 GMT

View Slide

REST examples
‣ Updating a resource
POST /articles/1234 HTTP/1.1
If-Match: 23709-12135125

Teddybear
red
30
15,95
19,95

HTTP/1.1 200 OK
Content-length: 0
Date: sun, 01 Nov 2010 12:34:56 GMT
HTTP/1.1 412 Precondition failed
Content-length: 0
Date: sun, 01 Nov 2010 12:34:56 GMT
Idempotent

View Slide

POST /user/jthijssen/address_merge HTTP/1.1
Content-type: text/csv;charset=UTF-8
John Doe, 1 Main Street, Seattle, WA
Jane Doe, 100 North Street, Los Angeles, CA
Location: /user/jthijssen/addressbook
‣ Controller resources

View Slide

More reading
‣ http://en.wikipedia.org/wiki/Representational_State_Transfer
‣ http://www.ics.uci.edu/~ﬁelding/pubs/dissertation/top.htm
‣ http://oreilly.com/catalog/9780596801694
‣ http://www.slideshare.net/Wombert/designing-http-interfaces-and-
restful-web-services-confoo11-20110310
‣ http://www.slideshare.net/adorepump/hateoas-the-confusing-bit-
from-rest
‣ http://www.slideshare.net/guilhermecaelum/rest-in-practice

View Slide

Question & discussion
http://farm1.static.ﬂickr.com/73/163450213_18478d3aa6_d.jpg

View Slide

‣ THANK YOU FOR YOUR ATTENTION

View Slide

REST and other important stuff

REST and other important stuff

Joshua Thijssen

More Decks by Joshua Thijssen

Other Decks in Programming

Featured

Transcript