Designing HTTP Interfaces and RESTful Web Services (IPC2012SE 2012-06-05)
Upcoming SlideShare
Loading in...5

Like this? Share it with your network


Designing HTTP Interfaces and RESTful Web Services (IPC2012SE 2012-06-05)

Uploaded on

Presentation given at International PHP Conference 2012 Spring Edition in Berlin, Germany.

Presentation given at International PHP Conference 2012 Spring Edition in Berlin, Germany.

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
    Be the first to like this
No Downloads


Total Views
On Slideshare
From Embeds
Number of Embeds



Embeds 610 362 122 61 53 6 2 1 1 1 1

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

    No notes for slide


  • 2. David Zuelke
  • 3. David Zülke
  • 4.ünchen_Panorama.JPG
  • 5. Founder
  • 6. Lead Developer
  • 7. @dzuelke
  • 8. THE OLDEN DAYS Before REST was En Vogue
  • 9.
  • 10. along came
  • 11.  dis is srs SEO bsns
  • 12. and said
  • 14. at least if they were
  • 15. so we had to make URLs "SEO friendly"
  • 16.
  • 17. and then things got out of control
  • 18. because nobody really had a clue
  • 19.
  • 20.
  • 21. oh dear…
  • 22. THE RISE OF WEB SERVICESOhai, Im ur CEO, I canhaz SOAP API plz, today, kthx?
  • 23. 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="">    <SOAP-­‐ENV:Body>        <ns1:getProduct  xmlns:ns1="">            <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="">    <SOAP-­‐ENV:Body>        <ns1:getProductResponse  xmlns:ns1="">            <product>                <id>123456</id>                <name>Red  Stapler</name>                <price>3.14</price>            </product>        </ns1:getProductResponse>    </SOAP-­‐ENV:Body></SOAP-­‐ENV:Envelope>
  • 24. 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="">    <SOAP-­‐ENV:Body>        <ns1:getProduct  xmlns:ns1="">            <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="">    <SOAP-­‐ENV:Body>        <SOAP-­‐ENV:Fault>            <faultcode>SOAP-­‐ENV:Server</faultcode>            <faultstring>Unknown  Product  </faultstring>        </SOAP-­‐ENV:Fault>    </SOAP-­‐ENV:Body></SOAP-­‐ENV:Envelope>
  • 25. SOAP sucks, said everyone
  • 26. lets build APIs without the clutter, they said
  • 27. example: the API
  • 28. 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>
  • 29. PROBLEMS WITH THIS API• Always a POST• Doesnt use HTTP Authentication• Operation information is enclosed in the request ("getdetail")• Nothing there is cacheable• Everything through one endpoint (/api/talks for talks)
  • 30. Level 0 in the Richardson Maturity Model: Plain old XML over the wire in an RPC fashion
  • 31. Room for improvement: use one URI for each resource.
  • 32. That would be Level 1 in Richardsons Maturity Model
  • 33. Level 0 and Level 1 are a bag of hurt. Do not use them. Ever.
  • 35. that was awesome
  • 36. because everyone could say
  • 37.  I haz REST nao
  • 38. when in fact
  • 39. they bloody didn’t
  • 40. RESTWhat Does That Even Mean?
  • 41. REpresentational State Transfer
  • 42. Roy Thomas Fielding: Architectural styles andthe design of network based software architectures.
  • 43. REST CONSTRAINTS• Client-Server• Stateless• Cacheable• Layered System• Code on Demand (optional)• Uniform Interface
  • 44. Simple explaination of the Uniform Interface
  • 45. UNIFORM INTERFACE•A URL identifies a Resource• 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
  • 46. a web page is not a resource
  • 47. it is a (complete) representation of a resource
  • 48. GETTING JSON BACKGET  /products/  HTTP/1.1Host:  acme.comAccept:  application/jsonHTTP/1.1  200  OKContent-­‐Type:  application/json;  charset=utf-­‐8Allow:  GET,  POST[    {        id:  1234,        name:  "Red  Stapler",        price:  3.14,        location:  ""    }]
  • 49. GETTING XML BACKGET  /products/  HTTP/1.1Host:  acme.comAccept:  application/xmlHTTP/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="">    <product  id="1234"  xl:type="simple"  xl:href="">        <name>Red  Stapler</name>        <price  currency="EUR">3.14</price>    </product></products>
  • 50. no hypermedia formats yet in those examples!
  • 51. I will show that in a few minutes
  • 52. AND FINALLY, HTMLGET  /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="">Red  Stapler</a>  (€3.14)</li>        </ul>    </body></html>
  • 53. VOLUME ONEDesigning an HTTP Interface
  • 54. FIRST: DEFINE RESOURCES A Good Approach: Structure Your URLs
  • 55. BAD URLS••• WTF?• new what?• sausage ID?•
  • 56. GOOD URLS a list of products• filtering is a query• a single product• all photos•••
  • 57. now heres the ironic part
  • 58. URLs dont matter once you have a fully RESTful interface
  • 59. but it’s helpful to think in terms of resources
  • 60. SECOND: USE RESOURCES CRUD, but not really
  • 61. COLLECTION OPERATIONS• • GET to retrieve a list of products • POST to create a new product • returns • 201 Created • Location:
  • 62. ITEM OPERATIONS• • GET to retrieve • PUT to update • DELETE to, you guessed it, delete
  • 63. and remember
  • 64. dont let the server maintain client state (e.g. cookies)
  • 65. Now we are at Level 2 in RMM
  • 66. 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
  • 67. THE TWITTER APINot RESTful, And Not Even Getting HTTP Right :(
  • 68. mind you were not even inspecting the RESTfulness
  • 69. were just looking at Twitters API from an HTTP perspective
  • 70. STATUSES/SHOW• GET• Problems: • Operation (“show”) included in the URL • Status ID not a child of the “statuses” collection• Better: GET with Accept header
  • 71. STATUSES/UPDATE• POST• Problems: • Operation (“update”) included in the URL • Uses the authenticated user implicitly• Better: POST
  • 72. STATUSES/DESTROY• POST• Problems: • Operation (“destroy”) included in the URL like it’s 1997 • Odd, illogical hierarchy again • Allows both “POST” and “DELETE” as verbs• Better: DELETE
  • 73. STATUSES/RETWEETS• GET• Problems: • Hierarchy is wrong• Better: GET
  • 74. STATUSES/RETWEET• PUT• 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
  • 75. SUMMARY• • POST to create a new tweet• • DELETE deletes (PUT could be used for updates)• • POST creates a new retweet
  • 76. ANGRY GERMAN SUMMARY• Twitters "REST" API sucks, hates HTTP and kills baby kittens.
  • 77. INTERMISSIONWhats the Biggest Reason for the Success of the Web?
  • 78. WWW
  • 79. first data exchange system
  • 80. planetary scale
  • 81. why is that possible?
  • 82. Hyperlinks!
  • 83. no tight coupling!
  • 84. loosely coupled by design
  • 85. no notification infrastructure
  • 86. HTTP/1.1 404 Not Found
  • 87. embraces failure
  • 88. more information != more friction
  • 89. no limits to scalability
  • 90. WWW is protocol-centric
  • 91. VOLUME TWORESTful Services with Hypermedia
  • 92. 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
  • 93. HATEOASThe Missing Piece in the Puzzle
  • 94. 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?
  • 95. 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!
  • 96. (X)HTML and Atom are Hypermedia formats
  • 97. Or you roll your own...
  • 98. A CUSTOM MEDIA TYPEGET  /products/1234  HTTP/1.1 Remind clients ofHost:  acme.comAccept:  application/ Uniform Interface :) re-use Atom forHTTP/1.1  200  OKContent-­‐Type:  application/;  charset=utf-­‐8 link relationsAllow:  GET,  PUT,  DELETE<?xml  version="1.0"  encoding="utf-­‐8"?><product  xmlns="urn:com.acme.prods"  xmlns:atom="">    <id>1234</id>    <name>Red  Stapler</name>    <price  currency="EUR">3.14</price>    <atom:link  rel="payment"  type="application/"                          href=""/></product> meaning defined in IANA Link Relations list
  • 99. boom, RMM Level 3
  • 100. XML is really good for hypermedia formats
  • 101. (hyperlinks, namespaced attributes, re-use of formats, …)
  • 102. JSON is more difficult
  • 103. (no hyperlinks, no namespaces, no element attributes)
  • 104. XML VERSUS JSON<?xml  version="1.0"  encoding="utf-­‐8"?><product  xmlns="urn:com.acme.prods"  xmlns:atom="">    <id>1234</id>    <name>Red  Stapler</name>    <price  currency="EUR">3.14</price>    <atom:link  rel="payment"  type="application/"                          href=""/></product>{    id:  1234,    name:  "Red  Stapler",    price:  {        amount:  3.14,        currency:  "EUR"    },    links:  [        {            rel:  "payment",            type:  "application/",            href:  ""        }    ]}
  • 105. also, JSON is hard to evolve without breaking clients
  • 106. <?xml  version="1.0"  encoding="utf-­‐8"?><products  xmlns="">    <product  id="123">        <name>Bacon</name>        <price>5.99</price>    </product></products>
  • 107. <?xml  version="1.0"  encoding="utf-­‐8"?><products  xmlns="">    <product  id="123">        <name>Bacon</name>        <price>5.99</price>        OMNOMNOM  Bacon    </product></products>
  • 108. <?xml  version="1.0"  encoding="utf-­‐8"?><products  xmlns="">    <product  id="123">        <name>Bacon</name>        <price>5.99</price>        <price  currency="EUR">4.49</price>    </product></products>
  • 109. <?xml  version="1.0"  encoding="utf-­‐8"?><products  xmlns="">    <product  id="123">        <name  xml:lang="en">Bacon</name>        <name  xml:lang="de">Speck</name>        <price>5.99</price>    </product></products>
  • 110. <?xml  version="1.0"  encoding="utf-­‐8"?><products  xmlns="">    <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>
  • 111. and hey
  • 112. without hypermedia, your HTTP interface is not RESTful
  • 113. that’s totally fineand sometimes even the only way to do it
  • 114. (e.g. CouchDB or S3 are never going to be RESTful)
  • 115. just avoid calling it a "REST API" :)
  • 116. good hypermedia format example: the Lovefilm API
  • 117. <?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=";items_per_page=1&amp;term=old"                rel="self"  title="self"/>    <link  href=";items_per_page=1&amp;term=old"                rel="next"  title="next"/>    <link  href=";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></id>        <adult>false</adult>        <number_of_ratings>574</number_of_ratings>        <rating>4</rating>        <category  scheme=""  term="games"/>        <category  scheme=""  term="Xbox"/>        <category  scheme=""  term="Adventure"/>        <category  scheme=""  term="Role-­‐playing"/>        <category  scheme=""  term="TBC"/>        <link  href=""                    rel=""  title="synopsis"/>        <link  href=""                    rel=""  title="reviews"/>        <link  href="­‐Star-­‐Wars-­‐Knights-­‐of-­‐the-­‐Old-­‐Republic.html?cid=LFAPI"                    rel="alternate"  title="web  page"/>    </catalog_title></search>
  • 118. 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• Shoulduse 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
  • 119. another great RESTful API: Huddle
  • 120. <document    xmlns=""    title="TPS  report  May  2010"    description="relentlessly  mundane  and  enervating.">        <link  rel="self"  href="..."  />    <link  rel="parent"  href="..."  title="..."/>    <link  rel="edit"  href="..."  />    <link  rel="delete"  href="..."  />    <link  rel="content"  href="..."  title="..."  type="..."  />    <link  rel="thumb"  href="..."  />    <link  rel="version-­‐history"  href="..."  />    <link  rel="create-­‐version"  href="..."  />    <link  rel="comments"  href="..."  />        <actor  name="Peter  Gibson"  rel="owner">        <link  rel="self"  href="..."  />        <link  rel="avatar"  href="..."  type="image/jpg"  />        <link  rel="alternate"  href="..."  type="text/html"  />    </actor>        <actor  name="Barry  Potter"  rel="updated-­‐by">        <link  rel="self"  href="..."  />        <link  rel="avatar"  href="..."  type="image/jpg"  />        <link  rel="alternate"  href="..."  type="text/html"  />    </actor>        <size>19475</size>        <version>98</version>    <created>2007-­‐10-­‐10T09:02:17Z</created>    <updated>2011-­‐10-­‐10T09:02:17Z</updated>    <processingStatus>Complete</processingStatus>    <views>9</views></document>
  • 121. ROOM FOR IMPROVEMENT IN THE HUDDLE API• Uses custom rels like “thumb” or “avatar” not defined in the IANA registry ( • Risk of collisions and ambiguity; should use something like “” instead.• Uses one global XML schema and namespace for all entities • Clients cannot detect entity type based on namespace • Difficult to evolve schema versions independently
  • 122. API VERSIONING Media Types To The Rescue!
  • 123. why not then
  • 124. different URLs means different resources!
  • 125. also, keep bookmarks (by machines) in mind
  • 126. API VERSION 1GET  /products  HTTP/1.1Host:  acme.comAccept:  application/  200  OKContent-­‐Type:  application/;  charset=utf-­‐8Allow:  GET,  POST<?xml  version="1.0"  encoding="utf-­‐8"?><products  xmlns="urn:com.acme.products"  xmlns:xl="">    <product  id="1234"  xl:type="simple"  xl:href="">        <name>Red  Stapler</name>        <price  currency="EUR">3.14</price>    </product></products>
  • 127. (some years pass...)
  • 128. API VERSION 2GET  /products  HTTP/1.1Host:  acme.comAccept:  application/  200  OKContent-­‐Type:  application/;  charset=utf-­‐8Allow:  GET,  POST<?xml  version="1.0"  encoding="utf-­‐8"?><products  xmlns="urn:com.acme.products"  xmlns:xl="">    <product  id="1234"  xl:type="simple"  xl:href="">        <name>Red  Stapler</name>        <price  currency="EUR">3.14</price>        <availability>false</availability>    </product></products>
  • 129. clients can’t upgrade protocol for known URLs!
  • 130. Also, imagine every install of phpBB or TYPO3 had an API
  • 131. If the version is in the URL, clients need to regex those
  • 132.
  • 133.
  • 134. that would be fail
  • 135. or what if another forum software wants the same API?
  • 136. also would have to use “/v1/” in their URLs
  • 137. URI based versioning kills interoperability
  • 138. YOU MIGHT BE WONDERING Why Exactly Is This Awesome?
  • 139. THE MERITS OF REST• Easyto evolve: add new • Easyto implement: build it features or elements without on top of HTTP, and profit! breaking BC • Authentication & TLS• Easy to learn: developers can "browse" service via link rels • Caching & Load Balancing• Easyto scale up: grows well • Conditional Requests with number of features, users and servers • Content Negotiation
  • 140. but...
  • 141. hold on, you say
  • 142. a plain HTTP-loving service does the job, you say
  • 143. surely, there is a merit to REST beyond extensibility, you ask
  • 144. nope
  • 145. "REST is software design on the scale of decades: everydetail is intended to promote software longevity andindependent evolution. Many of the constraints aredirectly opposed to short-term efficiency. Unfortunately,people are fairly good at short-term design, and usuallyawful at long-term design." Roy Fielding
  • 146. "Most of RESTs constraints are focused on preservingindependent evolvability over time, which is onlymeasurable on the scale of years. Most developerssimply dont care what happens to their product yearsafter it is deployed, or at least they expect to be aroundto rewrite it when such change occurs." Roy Fielding
  • 147. FURTHER READING• Ryan Tomayko How I Explained REST to my Wife• Jim Webber, Savas Parastatidis & Ian Robinson How to GET a Cup of Coffee• Roy Thomas Fielding Architectural Styles and the Design of Network-based Software Architectures
  • 148. BOOKS ON REST• Jim Webber, Savas Parastatidis, Ian Robinson REST in Practice ISBN: 978-0596805821• Subbu Allamaraju RESTful Web Services Cookbook ISBN: 978-0596801687• Leonard Richardson, Sam Ruby RESTful Web Services ISBN: 978-0596529260
  • 149. !e End
  • 150. Questions?
  • 151. THANK YOU! This was by @dzuelkeSend me questions or hire