Representation state transfer and some other important stuff

Representational
State
Transfer
(REST)
(and some other important stuff)

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

What is REST?

Roy Fielding said:
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.

What is REST?

‣ Cacheable
‣ Stateless
‣ Scalable
‣ Fault-tolerant
‣ Loosely coupled

‣ ADVANTAGES OF REST

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

What is REST?

‣ Identiﬁcation of resources
‣ Manipulation of resources
‣ Self-descriptive messages
‣ HATEOAS

‣ THE FOUR MAIN PRINCIPLES

Identiﬁcation of resources

‣ /index.php?action=getarticle&id=5
‣ /default/article/5/4/6/size

Cacheable? Scalable? Readable?

‣ You are doing it wrong... :(


‣ /articles
We want all articles

‣ /articles/5/photos/4/comments/1
We want the first comment of the fourth photo for the fifth article

‣ /articles/5/photos/4/comments
We want all comments of the fourth photo for the fifth article

Cacheable! Scalable! Readable!

‣ Readable and maintainable!


✗ /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

Manipulation of resources

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


‣ Create = PUT
‣ Retrieve = GET
‣ Update = POST
‣ Delete = DELETE

‣ CRUD to HTTP verb mapping


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

‣ SAFE METHODS


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

‣ IDEMPOTENT METHODS

Self-descriptive messages

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


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)



‣ HOW (content-type)



‣ WHAT



‣ WHEN



‣ WHO

HATEOAS

HATEOAS
=
Hypermedia As The Engine Of Application State

HATEOAS

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

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.

State inside your REST API

Fetch
Select Confirm Pay
E-Ticket

‣ “Flight booking API”


POST /search?order=price&limit=5 HTTP/1.1

<search>
<destination>LPA</destination>
<date>24-may-2011</date>
<type>firstclass</type>
</search>

‣ Search for speciﬁed ﬂights


HTTP/1.1 200 OK
Content-type: application/vnd.enrise.nl+xml ; version: 1.0

<flights xmlns=...>
<flight>
<flightno>KL1234</flightno>
<time>4:24</time>
<link method=”get” rel=”details” action=”/flight/15263” type=”text/xml”>
<link method=”post” rel=”confirm” action=”/confirm/flight/15263” type=”text/xml”>
</flight>
<flight>
<flightno>HV123</flightno>
<time>3:54</time>
<link method=”get” rel=”details” action=”/flight/523525” type=”text/xml”>
<link method=”post” rel=”confirm” action=”/confirm/flight/523525” type=”text/xml”>
</flight>
</flights>

‣ Returns a collection of ﬂights


POST /confirm/flight/15263 HTTP/1.1

<flight>
<seat>2A</seat>
<meal>vegetarian</meal>
</flight>

HTTP/1.1 401 Authentication required

‣ Confirm a specific flight


POST /confirm/flight/15263 HTTP/1.1
Authorization: OAuth ......

<flight>
<seat>2A</seat>
<meal>vegetarian</meal>
</flight>

HTTP/1.1 200 OK
Location: /booking/1616163

<booking>
<link rel=”details” href=”/booking/1616163” method=”get” type=”application/xml”>
<link rel=”payment” href=”/payment/booking/1616163” type=”application/xml”>
<link rel=”cancel” href=”/booking/1616163” method=”delete” type=”application/xml”>
</booking>

‣ Confirm a specific flight, with more info


OPTIONS /booking/1616163 HTTP/1.1

HTTP/1.1 200 OK
Allow: GET, DELETE, PUT

‣ What can we do with our booking?


DELETE /booking/1616163 HTTP/1.1

HTTP/1.1 204 No content

‣ Cancel our booking!


GET /booking/1616163 HTTP/1.1
Authorization: OAuth...

HTTP/1.1 200 OK

<booking>
<flight>
<time>4:24</time>
<link rel=”details” method=”get” href=”/flight/15263”>
</flight>
<payment>
<status>Not paid</status>
<link rel=”details” method=”get” href=”/payment/booking/1616163”>
<link rel=”pay” method=”post” href=”/payment/booking/1616163”>
</payment>
</booking>

‣ Still need to pay for the ﬂight


PUT /payment/booking/1616163 HTTP/1.1

<payment>
<cardno>4111-1111-1111-1111</cardno>
<expires>04/13</expires>
<name>Joshua Thijssen</name>
<amount currency=”eur”>414.00</amount>
</payment>

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

‣ Pay through another resource


OPTIONS /booking/1616163 HTTP/1.1

HTTP/1.1 200 OK
Allow: GET

‣ Can’t delete our booking since it’s paid


GET /booking/1616163 HTTP/1.1
Authorization: OAuth...

HTTP/1.1 200 OK

<booking>
<flight>
<time>4:24</time>
<link rel=”details” method=”get” href=”/flight/15263”>
</flight>
<payment>
<status>Paid in full</status>
<link rel=”details” method=”get” href=”/payment/booking/1616163”>
</payment>
<link rel=”eticket” method=”get” href=”/eticket/12415156261616”>
</booking>

‣ We can fetch our eticket now

(Common) pitfalls of REST design

‣ Versioning
‣ Methods in uri
‣ One uri per resource
‣ Controller resources
& non-CRUD


‣ Versioning
‣ Methods in uri
‣ One uri per resource
‣ Controller resources & Non-CRUD


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

‣ Versioning


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

Accept: application/vnd.enrise.nl+json ; version = 5.0.4a

‣ Versioning


‣ /api/get/articles/1234/photos
‣ /api/articles/new
‣ /api/articles/list

‣ Methods in URL


‣ /api/article/1234
‣ /api/article/red+teddybear
‣ Different resources

‣ One URI per resource


GET /api/article/red+teddybear HTTP/1.1

HTTP/1.1 303 See Other
Location: /api/article/1234

‣ One URI per resource


‣ Outside the CRUD?
‣ Multiple operations simultaneously?

‣ Controller resources & non-crud


POST /distance HTTP/1.1 GET /distance?from=...&to=.. HTTP/1.1
Host: www.enrise.com Host: www.enrise.com
Accept: text/xml Accept: text/xml
Content-type: text/xml;charset=UTF-8

<xml>
<from>Amersfoort, NLD</from>
<to>Apeldoorn, NLD</to>
</xml>

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

<result>
<distance unit=”km”>45</distance>
<distance unit=”miles”>27.96</distance>
</result>



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


More important stuff

‣ HTTP Status codes
‣ ETags

HTTP Status codes

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

HTTP Status codes

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

HTTP Status codes

‣ 200 OK
Resource returned

‣ 201 Created
Resource created

‣ 204 No content
Resource deleted

‣ IMPORTANT 2xx CODES

HTTP Status codes

‣ 304 Not modiﬁed
Resource wasn’t changed


HTTP Status codes

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


HTTP Status codes

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


HTTP Status codes

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


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

ETags & Optimistic locking

GET /blogpost/12345 HTTP/1.1

HTTP/1.1 200 OK
Content-length: 1234000
Content-type: text/xml
ETag: abcd-1234

<xml>
<blogpost>
<author>Joshua Thijssen</author>
<title>...</title>
....
</blogpost>
</xml>


GET /blogpost/12345 HTTP/1.1
If-None-Match: abcd-1234

HTTP/1.1 304 Not modified

Blogpost is cached and can be used!


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

<xml>
<author>Sjors de Valk</author>
</xml>

HTTP/1.1 412 Precondition failed

Blogpost is already modiﬁed by “someone”

REST examples

Other REST Examples

REST examples

PUT /articles HTTP/1.1
Content-type: application/vnd.enrise.nl+xml ; version = 1.0

<article xmlns=”http://www.enrise.com/article”>
<name>Teddybear</name>
<color>red</color>
<stock>15</stock>
<price currency=”eur”>15,95</price>
<price currency=”usd”>19,95</price>
</article>

HTTP/1.1 201 Created
Location: /articles/1234

‣ Creating a resource

REST examples

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

<articles xmlns=”http://www.enrise.com/article”>
<article>
<link method=”get” rel=”article” href=”/articles/1234”>
</article>
<article>
<name>Skippyball</name>
<link method=”get” rel=”article” href=”/articles/1121”>
</article>
</articles>

‣ Getting a resource collection

REST examples

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

<article xmlns=”http://www.enrise.com/article”>
...
</article>

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

‣ Getting a resource

REST examples

DELETE /articles/1234 HTTP/1.1

HTTP/1.1 204 No content
Content-length: 0
Date: sun, 01 Nov 2010 12:34:56 GMT

‣ Delete a resource

REST examples

POST /articles/1234 HTTP/1.1
Accept: application/vnd.enrise.nl+xml ; version = 1.0 Idempotent
If-Match: 23709-12135125

<article xmlns=”http://www.enrise.com/article>
<color>red</color>
<stock>30</stock>
<price currency=”eur”>15,95</price>
<price currency=”usd”>19,95</price>
</article>

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

‣ Updating a resource


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

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

Question & discussion

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

‣ THANK YOU FOR YOUR ATTENTION

Representation state transfer and some other important stuff

Empfohlen

Empfohlen

Weitere ähnliche Inhalte

Andere mochten auch

Andere mochten auch (18)

Ähnlich wie Representation state transfer and some other important stuff

Ähnlich wie Representation state transfer and some other important stuff (20)

Kürzlich hochgeladen

Kürzlich hochgeladen (20)

Representation state transfer and some other important stuff

Hinweis der Redaktion