designing url schemes and rest interfaces

84
DESIGNING URL SCHEMES AND REST INTERFACES 日本 PHP ユーザ会

Upload: david-zuelke

Post on 15-Jan-2015

7.780 views

Category:

Technology


2 download

DESCRIPTION

Presentation given at Japan PHP User Group meetup

TRANSCRIPT

Page 1: Designing URL Schemes and REST Interfaces

DESIGNING URL SCHEMESAND REST INTERFACES

日本 PHP ユーザ会

Page 2: Designing URL Schemes and REST Interfaces

David Zülke

Page 3: Designing URL Schemes and REST Interfaces

David Zuelke

Page 4: Designing URL Schemes and REST Interfaces
Page 5: Designing URL Schemes and REST Interfaces

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

Page 6: Designing URL Schemes and REST Interfaces

Founder

Page 8: Designing URL Schemes and REST Interfaces

Lead Developer

Page 11: Designing URL Schemes and REST Interfaces

THE OLDEN DAYSBefore REST Was En Vogue

Page 13: Designing URL Schemes and REST Interfaces

along came

Page 14: Designing URL Schemes and REST Interfaces

dis is srs SEO bsns

Page 15: Designing URL Schemes and REST Interfaces

and said

Page 16: Designing URL Schemes and REST Interfaces

NEIN NEIN NEIN NEIN

DAS IST VERBOTEN

Page 17: Designing URL Schemes and REST Interfaces

at least if they were

Page 18: Designing URL Schemes and REST Interfaces
Page 19: Designing URL Schemes and REST Interfaces

so we had to change this

Page 21: Designing URL Schemes and REST Interfaces

and then things got out of control

Page 22: Designing URL Schemes and REST Interfaces

because nobody really had a clue

Page 25: Designing URL Schemes and REST Interfaces

oh dear…

Page 26: Designing URL Schemes and REST Interfaces

ALONG CAME ROY FIELDINGAnd Gave Us REST

Page 27: Designing URL Schemes and REST Interfaces

that was awesome

Page 28: Designing URL Schemes and REST Interfaces

because everyone could say

Page 29: Designing URL Schemes and REST Interfaces

I haz REST nao

Page 30: Designing URL Schemes and REST Interfaces

when in fact

Page 31: Designing URL Schemes and REST Interfaces

they didn’t

Page 32: Designing URL Schemes and REST Interfaces

WHAT REST REALLY ISThis Won’t Take Long

Page 33: Designing URL Schemes and REST Interfaces

REpresentational State Transfer

Page 34: Designing URL Schemes and REST Interfaces

but what does that mean?

Page 35: Designing URL Schemes and REST Interfaces

•A URL identifies a Resource

•Resources have a hierarchy

•so you know that something with additional slashes is a subordinate resource

•Verbs are used to 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 36: Designing URL Schemes and REST Interfaces

and most importantly

Page 37: Designing URL Schemes and REST Interfaces

a web page is not a resource

Page 38: Designing URL Schemes and REST Interfaces

it is a representation of a resource

Page 39: Designing URL Schemes and REST Interfaces

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"    }]

Page 40: Designing URL Schemes and REST Interfaces

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>

Page 41: Designing URL Schemes and REST Interfaces

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>

Page 42: Designing URL Schemes and REST Interfaces

no hypermedia formats yet in those examples!

Page 43: Designing URL Schemes and REST Interfaces

I will show that in a few minutes

Page 44: Designing URL Schemes and REST Interfaces

A FEW EXAMPLESLet’s Start With Proper URL Design

Page 45: Designing URL Schemes and REST Interfaces

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 47: Designing URL Schemes and REST Interfaces

THE NEXT LEVELTime To Throw CRUD Into The Mix

Page 48: Designing URL Schemes and REST Interfaces

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 49: Designing URL Schemes and REST Interfaces

ITEM OPERATIONS

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

• GET to retrieve

• PUT to update

•DELETE to, you guessed it, delete

Page 50: Designing URL Schemes and REST Interfaces

(bonus points if you spotted the CRUD there)

Page 51: Designing URL Schemes and REST Interfaces

HATEOASThe Icing On The Cake

Page 52: Designing URL Schemes and REST Interfaces

ONE LAST PIECE IS MISSING

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

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

•What are the URLs for creating subordinate resources?

•Where is the contract for the service?

Page 53: Designing URL Schemes and REST Interfaces

HYPERMEDIA AS THE ENGINE OF APPLICATION STATE

•No tight coupling of operations

•No advance knowledge of operations necessary

•No definition up front necessary

•No breaking of clients if the implementation is updated!

Page 54: Designing URL Schemes and REST Interfaces

XHTML and Atom are Hypermedia formats

Page 55: Designing URL Schemes and REST Interfaces

Or you roll your own...

Page 56: Designing URL Schemes and REST Interfaces

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

HTTP/1.1  200  OKContent-­‐Type:  application/vnd.acmecorpshop+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/xlink">    <id>1234</id>    <name>Red  Stapler</name>    <price  currency="EUR">3.14</price>    <atom:link  rel="payment"  type="application/vnd.acmecorpshop+xml"                          href="http://acme.com/products/1234/payment"/></product>

re-use Atom forlink relations

meaning defined in Atom standard!

Page 57: Designing URL Schemes and REST Interfaces

XML is really good for hypermedia formats

Page 58: Designing URL Schemes and REST Interfaces

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

Page 59: Designing URL Schemes and REST Interfaces

JSON is more difficult

Page 60: Designing URL Schemes and REST Interfaces

(no namespaces, no attributes on elements)

Page 61: Designing URL Schemes and REST Interfaces

<?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/vnd.acmecorpshop+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.acmecorpshop+xml",            href:  "http://acme.com/products/1234/payment"        }    ]}

Page 62: Designing URL Schemes and REST Interfaces

YOU MIGHT BE WONDERINGWhy Exactly Is This Awesome?

Page 63: Designing URL Schemes and REST Interfaces

because it scales

Page 64: Designing URL Schemes and REST Interfaces

not just terms of performance

Page 65: Designing URL Schemes and REST Interfaces

but also in how you can extend it

Page 66: Designing URL Schemes and REST Interfaces

and how it interoperates with the Web of today

Page 67: Designing URL Schemes and REST Interfaces

it’s completely seamless

Page 68: Designing URL Schemes and REST Interfaces

all thanks to the polymorphism of URLs

Page 69: Designing URL Schemes and REST Interfaces

and all the features HTTP already has

Page 70: Designing URL Schemes and REST Interfaces

HTTP GOODIES

• Content Negotiation

• Redirection

• Authentication

• Transport Layer Security

• Caching

• Load Balancing

Page 71: Designing URL Schemes and REST Interfaces

just follow the one golden rule

Page 72: Designing URL Schemes and REST Interfaces

never, ever use any kind of state

Page 73: Designing URL Schemes and REST Interfaces

TWITTERS “REST” API, DISSECTED

Let’s Look At The Status Methods

Page 74: Designing URL Schemes and REST Interfaces

• GET http://api.twitter.com/1/statuses/show/id.format

• Problems:

•Operation (“show”) included in the URL

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

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

STATUSES/SHOW

Page 75: Designing URL Schemes and REST Interfaces

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

• Problems:

•Operation (“update”) included in the URL

• Uses the authenticated user implicitly

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

STATUSES/UPDATE

Page 76: Designing URL Schemes and REST Interfaces

• POST http://api.twitter.com/1/statuses/destroy/id.format

• Problems:

•Operation (“destroy”) included in the URL

•Odd hierarchy again

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

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

STATUSES/DESTROY

Page 78: Designing URL Schemes and REST Interfaces

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

• Problems:

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

• As usual, the operation is in the URL

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

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

STATUSES/RETWEET

Page 79: Designing URL Schemes and REST Interfaces

SUMMARY

• http://twitter.com/statuses/

• POST could create a new tweet, but I don’t really like that

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

•DELETE deletes, PUT could update

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

• POST creates a new retweet

Page 80: Designing URL Schemes and REST Interfaces

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 81: Designing URL Schemes and REST Interfaces

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 82: Designing URL Schemes and REST Interfaces

!e End

Page 83: Designing URL Schemes and REST Interfaces

Questions?