designing http interfaces and restful web services (zendcon 2011 2011-10-20)

148
DESIGNING HTTP INTERFACES AND RESTFUL WEB SERVICES

Upload: david-zuelke

Post on 10-May-2015

3.049 views

Category:

Technology


3 download

TRANSCRIPT

Page 1: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

DESIGNING HTTP INTERFACESAND RESTFUL WEB SERVICES

Page 2: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

David Zuelke

Page 3: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

David Zülke

Page 4: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)
Page 5: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

http://en.wikipedia.org/wiki/File:München_Panorama.JPG

Page 6: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

Founder

Page 8: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

Lead Developer

Page 11: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

THE OLDEN DAYSBefore REST was En Vogue

Page 13: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

along came

Page 14: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

dis is srs SEO bsns

Page 15: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

and said

Page 16: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

NEIN NEIN NEIN NEIN

DAS IST VERBOTEN

Page 17: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

at least if they were

Page 18: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)
Page 19: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

so we had to make URLs "SEO friendly"

Page 21: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

and then things got out of control

Page 22: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

because nobody really had a clue

Page 25: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

oh dear…

Page 26: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

THE RISE OF WEB SERVICESOhai, I'm ur CEO, I canhaz SOAP API plz, today, kthx?

Page 27: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

POST  /soapendpoint.php  HTTP/1.1Host:  localhostContent-­‐Type:  text/xml;  charset=utf-­‐8

<?xml  version="1.0"  encoding="UTF-­‐8"?><SOAP-­‐ENV:Envelope  xmlns:SOAP-­‐ENV="http://schemas.xmlsoap.org/soap/envelope/">    <SOAP-­‐ENV:Body>        <ns1:getProduct  xmlns:ns1="http://agavi.org/sampleapp">            <id>123456</id>        </ns1:getProduct>    </SOAP-­‐ENV:Body></SOAP-­‐ENV:Envelope>

HTTP/1.1  200  OKContent-­‐Type:  text/xml;  charset=utf-­‐8

<?xml  version="1.0"  encoding="UTF-­‐8"?><SOAP-­‐ENV:Envelope  xmlns:SOAP-­‐ENV="http://schemas.xmlsoap.org/soap/envelope/">    <SOAP-­‐ENV:Body>        <ns1:getProductResponse  xmlns:ns1="http://agavi.org/sampleapp">            <product>                <id>123456</id>                <name>Red  Stapler</name>                <price>3.14</price>            </product>        </ns1:getProductResponse>    </SOAP-­‐ENV:Body></SOAP-­‐ENV:Envelope>

Page 28: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

POST  /soapendpoint.php  HTTP/1.1Host:  localhostContent-­‐Type:  text/xml;  charset=utf-­‐8

<?xml  version="1.0"  encoding="UTF-­‐8"?><SOAP-­‐ENV:Envelope  xmlns:SOAP-­‐ENV="http://schemas.xmlsoap.org/soap/envelope/">    <SOAP-­‐ENV:Body>        <ns1:getProduct  xmlns:ns1="http://agavi.org/sampleapp">            <id>987654</id>        </ns1:getProduct>    </SOAP-­‐ENV:Body></SOAP-­‐ENV:Envelope>

HTTP/1.1  500  Internal  Service  ErrorContent-­‐Type:  text/xml;  charset=utf-­‐8

<?xml  version="1.0"  encoding="UTF-­‐8"?><SOAP-­‐ENV:Envelope  xmlns:SOAP-­‐ENV="http://schemas.xmlsoap.org/soap/envelope/">    <SOAP-­‐ENV:Body>        <SOAP-­‐ENV:Fault>            <faultcode>SOAP-­‐ENV:Server</faultcode>            <faultstring>Unknown  Product  </faultstring>        </SOAP-­‐ENV:Fault>    </SOAP-­‐ENV:Body></SOAP-­‐ENV:Envelope>

Page 29: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

SOAP sucks, said everyone

Page 30: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

let's build APIs without the clutter, they said

Page 31: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

example: the http://joind.in/ API

Page 32: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

POST  /api/talk  HTTP/1.1Host:  joind.inContent-­‐Type:  text/xml;  charset=utf-­‐8

<?xml  version="1.0"  encoding="UTF-­‐8"?><request>                <auth>                                <user>Chuck  Norris</user>                                <pass>roundhousekick</pass>                </auth>                <action  type="getdetail">                                <talk_id>42</talk_id>                </action></request>

HTTP/1.1  200  OKContent-­‐Type:  text/xml;  charset=utf-­‐8

<?xml  version="1.0"  encoding="UTF-­‐8"?><response>   <item>     <talk_title>My  Test  Talk</talk_title>     <talk_desc>This  is  a  sample  talk  description</talk_desc>     <ID>42</ID>   </item></response>

Page 33: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

PROBLEMS WITH THIS API

• Always a POST

• Doesn't use HTTP Authentication

• Operation information is enclosed in the request ("getdetail")

• Nothing there is cacheable

• Everything through one endpoint (/api/talks for talks)

Page 34: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

Level 0 in the Richardson Maturity Model:Plain old XML over the wire in an RPC fashion

Page 35: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

Room for improvement: use one URI for each resource.

Page 36: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

That would be Level 1 in Richardson's Maturity Model

Page 37: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

Level 0 and Level 1 are a bag of hurt.Do not use them.

Ever.

Page 38: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

ALONG CAME ROY FIELDINGAnd Gave Us REST

Page 39: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

that was awesome

Page 40: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

because everyone could say

Page 41: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

I haz REST nao

Page 42: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

when in fact

Page 43: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

they bloody didn’t

Page 44: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

RESTWhat Does That Even Mean?

Page 45: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

REpresentational State Transfer

Page 46: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

Roy Thomas Fielding: Architectural styles andthe design of network based software architectures.

Page 47: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

• Client-Server

• Stateless

• Cacheable

• Layered System

• Code on Demand (optional)

• Uniform Interface

REST CONSTRAINTS

Page 48: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

Simple explaination of the Uniform Interface

Page 49: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

•A URL identifies a Resource

•The URLs have an implicit hierarchy

•so you know that something with additional slashes is a subordinate resource (HTTP spec)

•Methods perform operations on resources

•The operation is implicit and not part of the URL

•A hypermedia format is used to represent the data

•Link relations are used to navigate a service

Page 50: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

a web page is not a resource

Page 51: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

it is a (complete) representation of a resource

Page 52: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

GET  /products/  HTTP/1.1Host:  acme.comAccept:  application/json

HTTP/1.1  200  OKContent-­‐Type:  application/json;  charset=utf-­‐8Allow:  GET,  POST

[    {        id:  1234,        name:  "Red  Stapler",        price:  3.14,        location:  "http://acme.com/products/1234"    }]

GETTING JSON BACK

Page 53: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

GET  /products/  HTTP/1.1Host:  acme.comAccept:  application/xml

HTTP/1.1  200  OKContent-­‐Type:  application/xml;  charset=utf-­‐8Allow:  GET,  POST

<?xml  version="1.0"  encoding="utf-­‐8"?><products  xmlns="urn:com.acme.products"  xmlns:xl="http://www.w3.org/1999/xlink">    <product  id="1234"  xl:type="simple"  xl:href="http://acme.com/products/1234">        <name>Red  Stapler</name>        <price  currency="EUR">3.14</price>    </product></products>

GETTING XML BACK

Page 54: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

no hypermedia formats yet in those examples!

Page 55: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

I will show that in a few minutes

Page 56: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

GET  /products/  HTTP/1.1Host:  acme.comAccept:  application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,*/*;q=0.5User-­‐Agent:  Mozilla/5.0  (Macintosh;  U;  Intel  Mac  OS  X  10_5_8;  en-­‐us)  AppleWebKit…

HTTP/1.1  200  OKContent-­‐Type:  text/html;  charset=utf-­‐8Allow:  GET,  POST

<html  lang="en">    <head>        <meta  http-­‐equiv="Content-­‐Type"  content="text/html;  charset=UTF-­‐8"></meta>        <title>ACME  Inc.  Products</title>    </head>    <body>        <h1>Our  Incredible  Products</h1>        <ul  id="products">            <li><a  href="http://acme.com/products/1234">Red  Stapler</a>  (€3.14)</li>        </ul>    </body></html>

AND FINALLY, HTML

Page 57: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

VOLUME ONEDesigning an HTTP Interface

Page 58: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

A FEW EXAMPLESLet’s Start With Proper URL Design

Page 59: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

BAD URLS

• http://www.acme.com/product/

• http://www.acme.com/product/filter/cats/desc

• http://www.acme.com/product/1234

• http://www.acme.com/photos/product/1234

• http://www.acme.com/photos/product/1234/new

• http://www.acme.com/photos/product/1234/5678

WTF?

sausage ID?

new what?

Page 61: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

now here's the ironic part

Page 62: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

URLs don't matter once you have a fully RESTful interface

Page 63: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

but it helps to think in terms of resources

Page 64: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

THE NEXT LEVELTime To Throw CRUD Into The Mix

Page 65: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

COLLECTION OPERATIONS

• http://www.acme.com/products/

• GET to retrieve a list of products

• POST to create a new product

• returns

• 201 Created

• Location: http://www.acme.com/products/1235

Page 66: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

ITEM OPERATIONS

• http://www.acme.com/products/1234

• GET to retrieve

• PUT to update

• DELETE to, you guessed it, delete

Page 67: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

but please

Page 68: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

don't let the server maintain client state (e.g. cookies)

Page 69: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

Now we are at Level 2 in RMM

Page 70: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

RMM LEVEL 2

• Use HTTP verbs

• GET (safe and idempotent)

• POST (unsafe, not idempotent)

• PUT & DELETE (unsafe, idempotent)

• Use HTTP status codes to indicate result success

• e.g. HTTP/1.1 409 Conflict

Page 71: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

TWITTERS “REST” API, DISSECTED

(well, not the whole API; just the status methods will do)

Page 72: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

mind you we're not even inspecting the RESTfulness

Page 73: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

we're just looking at Twitter's API from an HTTP perspective

Page 74: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

• GET http://api.twitter.com/1/statuses/show/12345.json

• Problems:

• Operation (“show”) included in the URL

• Status ID not a child of the “statuses” collection

• Better : GET http://twitter.com/statuses/12345 with Accept header

STATUSES/SHOW

Page 75: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

• POST http://api.twitter.com/1/statuses/update.json

• Problems:

• Operation (“update”) included in the URL

• Uses the authenticated user implicitly

• Better : POST http://twitter.com/users/scottmac/statuses/

STATUSES/UPDATE

Page 76: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

• POST http://api.twitter.com/1/statuses/destroy/12345.json

• Problems:

• Operation (“destroy”) included in the URL like it’s 1997

• Odd, illogical hierarchy again

• Allows both “POST” and “DELETE” as verbs

• Better : DELETE http://twitter.com/statuses/12345

STATUSES/DESTROY

Page 77: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

• GET http://api.twitter.com/1/statuses/retweets/12345.json

• Problems:

• Hierarchy is wrong

• Better : GET http://twitter.com/statuses/12345/retweets/

STATUSES/RETWEETS

Page 78: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

• PUT http://api.twitter.com/1/statuses/retweet/12345.format

• Problems:

• “retweets” collection exists, but is not used here

• As usual, the action is in the URL (“make retweet” is RPC-y)

• Allows both “PUT” and “POST” as verbs

• Better : POST http://twitter.com/statuses/12345/retweets/

STATUSES/RETWEET

Page 79: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

SUMMARY

• http://twitter.com/statuses/

• POST to create a new tweet

• http://twitter.com/statuses/12345

• DELETE deletes (PUT could be used for updates)

• http://twitter.com/statuses/12345/retweets/

• POST creates a new retweet

Page 80: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

ANGRY GERMAN SUMMARY

• Twitter's "REST" API sucks, hates HTTP and kills baby kittens.

Page 81: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

INTERMISSIONWhat's the Biggest Reason for the Success of the Web?

Page 82: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

WWW

Page 83: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

first data exchange system

Page 84: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

planetary scale

Page 85: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)
Page 86: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)
Page 87: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)
Page 88: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

why is that possible?

Page 89: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

Hyperlinks!

Page 90: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

no tight coupling!

Page 91: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

loosely coupled by design

Page 92: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

no notification infrastructure

Page 93: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

HTTP/1.1 404 Not Found

Page 94: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

embraces failure

Page 95: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

more information != more friction

Page 96: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

no limits to scalability

Page 97: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

WWW is protocol-centric

Page 98: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

VOLUME TWORESTful Services with Hypermedia

Page 99: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

THE UNIFORM INTERFACE

• Identification of Resources (e.g. through URIs)

• Representations are conceptually separate!

• Manipulation Through Representations (i.e. they are complete)

• Self-Descriptive Messages (containing all information)

• Hypermedia As The Engine Of Application State ("HATEOAS")

magic awesomesauce essential to REST

Page 100: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

HATEOASThe Missing Piece in the Puzzle

Page 101: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

ONE LAST PIECE IS MISSING

• How does a client know what to do with representations?

• How do you go to the “next” operation?

• What are the URLs for creating subordinate resources?

• Where is the contract for the service?

Page 102: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

HYPERMEDIA AS THE ENGINE OF APPLICATION STATE

• Use links to allow clients to discover locations and operations

• Link relations are used to express the possible options

• Clients do not need to know URLs, so they can change

• The entire application workflow is abstracted, thus changeable

• The hypermedia type itself could be versioned if necessary

• No breaking of clients if the implementation is updated!

Page 103: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

(X)HTML and Atom are Hypermedia formats

Page 104: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

Or you roll your own...

Page 105: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

GET  /products/1234  HTTP/1.1Host:  acme.comAccept:  application/vnd.com.acme.shop+xml

HTTP/1.1  200  OKContent-­‐Type:  application/vnd.come.acme.shop+xml;  charset=utf-­‐8Allow:  GET,  PUT,  DELETE

<?xml  version="1.0"  encoding="utf-­‐8"?><product  xmlns="urn:com.acme.prods"  xmlns:atom="http://www.w3.org/2005/Atom">    <id>1234</id>    <name>Red  Stapler</name>    <price  currency="EUR">3.14</price>    <atom:link  rel="payment"  type="application/vnd.com.acme.shop+xml"                          href="http://acme.com/products/1234/payment"/></product>

re-use Atom forlink relations

meaning defined in IANA Link Relations list

A CUSTOM MEDIA TYPE

Remind clients ofUniform Interface :)

Page 106: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

boom, RMM Level 3

Page 107: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

XML is really good for hypermedia formats

Page 108: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

(hyperlinks, namespaced attributes, re-use of formats, …)

Page 109: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

JSON is more difficult

Page 110: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

(no hyperlinks, no namespaces, no element attributes)

Page 111: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

<?xml  version="1.0"  encoding="utf-­‐8"?><product  xmlns="urn:com.acme.prods"  xmlns:atom="http://www.w3.org/2005/xlink">    <id>1234</id>    <name>Red  Stapler</name>    <price  currency="EUR">3.14</price>    <atom:link  rel="payment"  type="application/com.acme.shop+xml"                          href="http://acme.com/products/1234/payment"/></product>

{    id:  1234,    name:  "Red  Stapler",    price:  {        amount:  3.14,        currency:  "EUR"    },    links:  [        {            rel:  "payment",            type:  "application/vnd.com.acme.shop+json",            href:  "http://acme.com/products/1234/payment"        }    ]}

XML VERSUS JSON

Page 112: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

also, JSON is hard to evolve without breaking clients

Page 113: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

<?xml  version="1.0"  encoding="utf-­‐8"?><products  xmlns="http://acme.com/shop/products">    <product  id="123">        <name>Bacon</name>        <price>5.99</price>    </product></products>

Page 114: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

<?xml  version="1.0"  encoding="utf-­‐8"?><products  xmlns="http://acme.com/shop/products">    <product  id="123">        <name>Bacon</name>        <price>5.99</price>        OMNOMNOM  Bacon    </product></products>

Page 115: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

<?xml  version="1.0"  encoding="utf-­‐8"?><products  xmlns="http://acme.com/shop/products">    <product  id="123">        <name>Bacon</name>        <price>5.99</price>        <price  currency="EUR">4.49</price>    </product></products>

Page 116: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

<?xml  version="1.0"  encoding="utf-­‐8"?><products  xmlns="http://acme.com/shop/products">    <product  id="123">        <name  xml:lang="en">Bacon</name>        <name  xml:lang="de">Speck</name>        <price>5.99</price>    </product></products>

Page 117: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

<?xml  version="1.0"  encoding="utf-­‐8"?><products  xmlns="http://acme.com/shop/products">    <product  id="123">        <name  xml:lang="en">Bacon</name>        <name  xml:lang="de">Speck</name>        <price>5.99</price>        <link  rel="category"  href="..."  />    </product></products>

Page 118: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

and hey

Page 119: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

without hypermedia, your HTTP interface is not RESTful

Page 120: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

that’s totally fineand sometimes even the only way to do it

Page 121: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

(e.g. CouchDB or S3 are never going to be RESTful)

Page 122: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

just avoid calling it a "REST API" :)

Page 123: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

one more hypermedia format example: the Lovefilm API

Page 124: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

<?xml  version="1.0"  encoding="utf-­‐8"  standalone="yes"?><search>    <total_results>6</total_results>    <items_per_page>1</items_per_page>    <start_index>1</start_index>    <link  href="http://openapi.lovefilm.com/catalog/games?start_index=1&amp;items_per_page=1&amp;term=old"                rel="self"  title="self"/>    <link  href="http://openapi.lovefilm.com/catalog/games?start_index=2&amp;items_per_page=1&amp;term=old"                rel="next"  title="next"/>    <link  href="http://openapi.lovefilm.com/catalog/games?start_index=6&amp;items_per_page=1&amp;term=old"                rel="last"  title="last"/>    <catalog_title>        <can_rent>true</can_rent>        <release_date>2003-­‐09-­‐12</release_date>        <title  full="Star  Wars:  Knights  of  the  Old  Republic"  clean="Star  Wars:  Knights  of  the  Old  Republic"/>        <id>http://openapi.lovefilm.com/catalog/title/59643</id>        <adult>false</adult>        <number_of_ratings>574</number_of_ratings>        <rating>4</rating>        <category  scheme="http://openapi.lovefilm.com/categories/catalog"  term="games"/>        <category  scheme="http://openapi.lovefilm.com/categories/format"  term="Xbox"/>        <category  scheme="http://openapi.lovefilm.com/categories/genres"  term="Adventure"/>        <category  scheme="http://openapi.lovefilm.com/categories/genres"  term="Role-­‐playing"/>        <category  scheme="http://openapi.lovefilm.com/categories/certificates/bbfc"  term="TBC"/>        <link  href="http://openapi.lovefilm.com/catalog/title/59643/synopsis"                    rel="http://schemas.lovefilm.com/synopsis"  title="synopsis"/>        <link  href="http://openapi.lovefilm.com/catalog/title/59643/reviews"                    rel="http://schemas.lovefilm.com/reviews"  title="reviews"/>        <link  href="http://www.lovefilm.com/product/59643-­‐Star-­‐Wars-­‐Knights-­‐of-­‐the-­‐Old-­‐Republic.html?cid=LFAPI"                    rel="alternate"  title="web  page"/>    </catalog_title></search>

Page 125: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

ROOM FOR IMPROVEMENT IN THE LOVEFILM API

• Uses application/xml instead of a custom media type

• Once that is fixed, all the link elements could also have a “type” attribute indicating the media type

• Should use XML namespaces on the root element, with one namespace per type (e.g. “urn:com.lovefilm.api.item”, “urn:com.lovefilm.api.searchresult” and so on)

• That way, clients can determine the resource type easily

Page 126: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

HOSTS AND VERSIONING

• Q: Why not http://api.twitter.com/ ?

• A: Because http://api.twitter.com/statuses/1234 and http://twitter.com/statuses/1234 would be different resources!

• Q: What about /1/ or /2/ for versioning?

• A: Again, different resources. Instead, use the media type:application/vnd.com.twitter.api.v1+xml orapplication/vnd.com.twitter.api+xml;ver=2

Page 127: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

Also, imagine every install of phpBB or TYPO3 had an API

Page 128: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

If the version is in the URL, clients need to regex those

Page 129: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

http://sharksforum.org/community/api/v1/threads/102152

Page 130: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

http://forum.sharksforum.org/api/v1/threads/102152

Page 131: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

that would be fail

Page 132: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

or what if another forum software wants the same API?

Page 133: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

also would have to use “/v1/” in their URLs

Page 134: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

URI based versioning kills interoperability

Page 135: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

YOU MIGHT BE WONDERINGWhy Exactly Is This Awesome?

Page 136: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

THE MERITS OF REST

• Easy to evolve: add new features or elements without breaking BC

• Easy to learn: developers can "browse" service via link rels

• Easy to scale up: grows well with number of features, users and servers

• Easy to implement: build it on top of HTTP, and profit!

• Authentication & TLS

• Caching & Load Balancing

• Conditional Requests

• Content Negotiation

Page 137: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

but...

Page 138: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

hold on, you say

Page 139: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

a plain HTTP-loving service does the job, you say

Page 140: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

surely, there is a merit to REST beyond extensibility, you ask

Page 141: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

nope

Page 142: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

"REST is software design on the scale of decades: every detail is intended to promote software longevity and independent evolution. Many of the constraints are directly opposed to short-term efficiency. Unfortunately, people are fairly good at short-term design, and usually awful at long-term design."

Roy Fielding

Page 143: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

"Most of REST's constraints are focused on preserving independent evolvability over time, which is only measurable on the scale of years. Most developers simply don't care what happens to their product years after it is deployed, or at least they expect to be around to rewrite it when such change occurs."

Roy Fielding

Page 144: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

FURTHER READING

• Ryan TomaykoHow I Explained REST to my Wifehttp://tomayko.com/writings/rest-to-my-wife

• Jim Webber, Savas Parastatidis & Ian RobinsonHow to GET a Cup of Coffeehttp://www.infoq.com/articles/webber-rest-workflow

• Roy Thomas FieldingArchitectural Styles and the Design of Network-based Software Architectureshttp://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

Page 145: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

BOOKS ON REST

• Jim Webber, Savas Parastatidis, Ian RobinsonREST in PracticeISBN: 978-0596805821

• Subbu AllamarajuRESTful Web Services CookbookISBN: 978-0596801687

• Leonard Richardson, Sam RubyRESTful Web ServicesISBN: 978-0596529260

Page 146: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

!e End

Page 147: Designing HTTP Interfaces and RESTful Web Services (ZendCon 2011 2011-10-20)

Questions?