Designing URL Schemes and REST Interfaces

  • 7,705 views
Uploaded on

Presentation given at Japan PHP User Group meetup

Presentation given at Japan PHP User Group meetup

More in: Technology
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Be the first to comment
No Downloads

Views

Total Views
7,705
On Slideshare
0
From Embeds
0
Number of Embeds
0

Actions

Shares
Downloads
63
Comments
0
Likes
6

Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    No notes for slide

Transcript

  • 1. DESIGNING URL SCHEMES AND REST INTERFACES PHP
  • 2. David Zülke
  • 3. David Zuelke
  • 4. http://en.wikipedia.org/wiki/File:München_Panorama.JPG
  • 5. Founder
  • 6. Lead Developer
  • 7. @dzuelke
  • 8. THE OLDEN DAYS Before REST Was En Vogue
  • 9. http://www.acme.com/index.php?action=zomg&page=lol
  • 10. along came
  • 11.  dis is srs SEO bsns
  • 12. and said
  • 13. NEIN NEIN NEIN NEIN DAS IST VERBOTEN
  • 14. at least if they were
  • 15. so we had to change this
  • 16. http://www.acme.com/zomg/lol
  • 17. and then things got out of control
  • 18. because nobody really had a clue
  • 19. http://acme.com/videos/latest/hamburgers
  • 20. http://acme.com/search/lolcats/pictures/yes/1/200
  • 21. oh dear…
  • 22. ALONG CAME ROY FIELDING And Gave Us REST
  • 23. that was awesome
  • 24. because everyone could say
  • 25.  I haz REST nao
  • 26. when in fact
  • 27. they didn’t
  • 28. WHAT REST REALLY IS This Won’t Take Long
  • 29. REpresentational State Transfer
  • 30. but what does that mean?
  • 31. •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
  • 32. and most importantly
  • 33. a web page is not a resource
  • 34. it is a representation of a resource
  • 35. GET  /products/  HTTP/1.1 Host:  acme.com Accept:  application/json HTTP/1.1  200  OK Content-­‐Type:  application/json;  charset=utf-­‐8 Allow:  GET,  POST [    {        id:  1234,        name:  "Red  Stapler",        price:  3.14,        location:  "http://acme.com/products/1234"    } ]
  • 36. GET  /products/  HTTP/1.1 Host:  acme.com Accept:  application/xml HTTP/1.1  200  OK Content-­‐Type:  application/xml;  charset=utf-­‐8 Allow:  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>
  • 37. GET  /products/  HTTP/1.1 Host:  acme.com Accept:  application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,*/*;q=0.5 User-­‐Agent:  Mozilla/5.0  (Macintosh;  U;  Intel  Mac  OS  X  10_5_8;  en-­‐us)  AppleWebKit… HTTP/1.1  200  OK Content-­‐Type:  text/html;  charset=utf-­‐8 Allow:  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>
  • 38. no hypermedia formats yet in those examples!
  • 39. I will show that in a few minutes
  • 40. A FEW EXAMPLES Let’s Start With Proper URL Design
  • 41. BAD URLS • http://www.acme.com/product/ • http://www.acme.com/product/filter/cats/desc • http://www.acme.com/product/1234 WTF? • http://www.acme.com/photos/product/1234 new what? • http://www.acme.com/photos/product/1234/new sausage ID? • http://www.acme.com/photos/product/1234/5678
  • 42. GOOD URLS a list of products • http://www.acme.com/products/ filtering is a query • http://www.acme.com/products/?filter=cats&sort=desc a single product • http://www.acme.com/products/1234 all photos • http://www.acme.com/products/1234/photos/ • http://www.acme.com/products/1234/photos/?sort=latest • http://www.acme.com/products/1234/photos/5678
  • 43. THE NEXT LEVEL Time To Throw CRUD Into The Mix
  • 44. 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
  • 45. ITEM OPERATIONS • http://www.acme.com/products/1234 • GET to retrieve • PUT to update • DELETE to, you guessed it, delete
  • 46. (bonus points if you spotted the CRUD there)
  • 47. HATEOAS The Icing On The Cake
  • 48. 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?
  • 49. 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!
  • 50. XHTML and Atom are Hypermedia formats
  • 51. Or you roll your own...
  • 52. GET  /products/1234  HTTP/1.1 Host:  acme.com Accept:  application/vnd.acmecorpshop+xml re-use Atom for HTTP/1.1  200  OK Content-­‐Type:  application/vnd.acmecorpshop+xml;  charset=utf-­‐8 link relations Allow:  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> meaning defined in Atom standard!
  • 53. XML is really good for hypermedia formats
  • 54. (namespaces, namespaced attributes, re-use of formats, …)
  • 55. JSON is more difficult
  • 56. (no namespaces, no attributes on elements)
  • 57. <?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"        }    ] }
  • 58. YOU MIGHT BE WONDERING Why Exactly Is This Awesome?
  • 59. because it scales
  • 60. not just terms of performance
  • 61. but also in how you can extend it
  • 62. and how it interoperates with the Web of today
  • 63. it’s completely seamless
  • 64. all thanks to the polymorphism of URLs
  • 65. and all the features HTTP already has
  • 66. HTTP GOODIES • Content Negotiation • Redirection • Authentication • Transport Layer Security • Caching • Load Balancing
  • 67. just follow the one golden rule
  • 68. never, ever use any kind of state
  • 69. TWITTERS “REST” API, DISSECTED Let’s Look At The Status Methods
  • 70. STATUSES/SHOW • 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
  • 71. STATUSES/UPDATE • 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/
  • 72. STATUSES/DESTROY • 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
  • 73. STATUSES/RETWEETS • GET http://api.twitter.com/1/statuses/retweets/id.format • Problems: • Hierarchy is wrong • Better: GET http://twitter.com/statuses/id/retweets/
  • 74. STATUSES/RETWEET • 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/
  • 75. 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
  • 76. 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 or application/vnd.com.twitter.api+xml;ver=2
  • 77. FURTHER READING • Ryan Tomayko How I Explained REST to my Wife http://tomayko.com/writings/rest-to-my-wife • Jim Webber, Savas Parastatidis & Ian Robinson How to GET a Cup of Coffee http://www.infoq.com/articles/webber-rest-workflow • Roy Thomas Fielding Architectural Styles and the Design of Network-based Software Architectures http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
  • 78. !e End
  • 79. Questions?
  • 80. THANK YOU! This was a presentation by @dzuelke Send me an e-mail! david.zuelke@bitextender.com