Your SlideShare is downloading. ×
0
DESIGNING HTTP INTERFACESAND RESTFUL WEB SERVICES
David Zuelke
David Zülke
http://en.wikipedia.org/wiki/File:München_Panorama.JPG
Founder
Lead Developer
@dzuelke
THE OLDEN DAYS  Before REST was En Vogue
http://www.acme.com/index.php?action=zomg&page=lol
along came
    dis is srs SEO bsns
and said
NEIN NEINNEIN NEIN DAS ISTVERBOTEN
at least if they were
so we had to make URLs "SEO friendly"
http://www.acme.com/zomg/lol
and then things got out of control
because nobody really had a clue
http://acme.com/videos/latest/hamburgers
http://acme.com/search/lolcats/pictures/yes/1/200
oh dear…
THE RISE OF WEB SERVICESOhai, Im ur CEO, I canhaz SOAP API plz, today, kthx?
POST  /soapendpoint.php  HTTP/1.1Host:  localhostContent-­‐Type:  text/xml;  charset=utf-­‐8<?xml  version="1.0"  encoding...
POST  /soapendpoint.php  HTTP/1.1Host:  localhostContent-­‐Type:  text/xml;  charset=utf-­‐8<?xml  version="1.0"  encoding...
SOAP sucks, said everyone
lets build APIs without the clutter, they said
example: the http://joind.in/ API
POST  /api/talk  HTTP/1.1Host:  joind.inContent-­‐Type:  text/xml;  charset=utf-­‐8<?xml  version="1.0"  encoding="UTF-­‐8...
PROBLEMS WITH THIS API• Always   a POST• Doesnt   use HTTP Authentication• Operation    information is enclosed in the req...
Level 0 in the Richardson Maturity Model: Plain old XML over the wire in an RPC fashion
Room for improvement: use one URI for each resource.
That would be Level 1 in Richardsons Maturity Model
Level 0 and Level 1 are a bag of hurt.          Do not use them.                Ever.
ALONG CAME ROY FIELDING       And Gave Us REST
that was awesome
because everyone could say
    I haz REST nao
when in fact
they bloody didn’t
RESTWhat Does That Even Mean?
REpresentational State Transfer
Roy Thomas Fielding: Architectural styles andthe design of network based software architectures.
REST CONSTRAINTS• Client-Server• Stateless• Cacheable• Layered     System• Code   on Demand (optional)• Uniform     Interf...
Simple explaination of the Uniform Interface
UNIFORM INTERFACE•A   URL identifies a Resource• Methods    perform operations on resources• The    operation is implicit a...
a web page is not a resource
it is a (complete) representation of a resource
GETTING JSON BACKGET  /products/  HTTP/1.1Host:  acme.comAccept:  application/jsonHTTP/1.1  200  OKContent-­‐Type:  applic...
GETTING XML BACKGET  /products/  HTTP/1.1Host:  acme.comAccept:  application/xmlHTTP/1.1  200  OKContent-­‐Type:  applicat...
no hypermedia formats yet in those examples!
I will show that in a few minutes
AND FINALLY, HTMLGET  /products/  HTTP/1.1Host:  acme.comAccept:  application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,*...
VOLUME ONEDesigning an HTTP Interface
FIRST: DEFINE RESOURCES   A Good Approach: Structure Your URLs
BAD URLS• http://www.acme.com/product/• http://www.acme.com/product/filter/cats/desc• http://www.acme.com/product/1234     ...
GOOD URLS                                  a list of products• http://www.acme.com/products/                              ...
now heres the ironic part
URLs dont matter once you have a fully RESTful interface
but it’s helpful to think in terms of resources
SECOND: USE RESOURCES      CRUD, but not really
COLLECTION OPERATIONS• http://www.acme.com/products/ • GET   to retrieve a list of products • POST   to create a new produ...
ITEM OPERATIONS• http://www.acme.com/products/1234 • GET   to retrieve • PUT   to update • DELETE    to, you guessed it, d...
and remember
dont let the server maintain client state (e.g. cookies)
Now we are at Level 2 in RMM
RMM LEVEL 2• Use   HTTP verbs • GET    (safe and idempotent) • POST     (unsafe, not idempotent) • PUT    & DELETE (unsafe...
THE TWITTER APINot RESTful, And Not Even Getting HTTP Right :(
mind you were not even inspecting the RESTfulness
were just looking at Twitters API from an HTTP perspective
STATUSES/SHOW• GET   http://api.twitter.com/1/statuses/show/12345.json• Problems: • Operation    (“show”) included in the ...
STATUSES/UPDATE• POST   http://api.twitter.com/1/statuses/update.json• Problems: • Operation   (“update”) included in the ...
STATUSES/DESTROY• POST   http://api.twitter.com/1/statuses/destroy/12345.json• Problems: • Operation   (“destroy”) include...
STATUSES/RETWEETS• GET   http://api.twitter.com/1/statuses/retweets/12345.json• Problems: • Hierarchy    is wrong• Better:...
STATUSES/RETWEET• PUT   http://api.twitter.com/1/statuses/retweet/12345.format• Problems: • “retweets” collection   exists...
SUMMARY• http://twitter.com/statuses/  • POST   to create a new tweet• http://twitter.com/statuses/12345  • DELETE   delet...
ANGRY GERMAN SUMMARY• Twitters   "REST" API sucks, hates HTTP and kills baby kittens.
INTERMISSIONWhats the Biggest Reason for the Success of the Web?
WWW
first data exchange system
planetary scale
why is that possible?
Hyperlinks!
no tight coupling!
loosely coupled by design
no notification infrastructure
HTTP/1.1 404 Not Found
embraces failure
more information != more friction
no limits to scalability
WWW is protocol-centric
VOLUME TWORESTful Services with Hypermedia
THE UNIFORM INTERFACE• Identification   of Resources (e.g. through URIs)  • Representations    are conceptually separate!• ...
HATEOASThe Missing Piece in the Puzzle
ONE LAST PIECE IS MISSING• How   does a client know what to do with representations?• How   do you go to the “next” operat...
HYPERMEDIA AS THE ENGINE   OF APPLICATION STATE• Use    links to allow clients to discover locations and operations• Link ...
(X)HTML and Atom are Hypermedia formats
Or you roll your own...
A CUSTOM MEDIA TYPEGET  /products/1234  HTTP/1.1              Remind clients ofHost:  acme.comAccept:  application/vnd.com...
boom, RMM Level 3
XML is really good for hypermedia formats
(hyperlinks, namespaced attributes, re-use of formats, …)
JSON is more difficult
(no hyperlinks, no namespaces, no element attributes)
XML VERSUS JSON<?xml  version="1.0"  encoding="utf-­‐8"?><product  xmlns="urn:com.acme.prods"  xmlns:atom="http://www.w3.o...
also, JSON is hard to evolve without breaking clients
<?xml  version="1.0"  encoding="utf-­‐8"?><products  xmlns="http://acme.com/shop/products">    <product  id="123">        ...
<?xml  version="1.0"  encoding="utf-­‐8"?><products  xmlns="http://acme.com/shop/products">    <product  id="123">        ...
<?xml  version="1.0"  encoding="utf-­‐8"?><products  xmlns="http://acme.com/shop/products">    <product  id="123">        ...
<?xml  version="1.0"  encoding="utf-­‐8"?><products  xmlns="http://acme.com/shop/products">    <product  id="123">        ...
<?xml  version="1.0"  encoding="utf-­‐8"?><products  xmlns="http://acme.com/shop/products">    <product  id="123">        ...
and hey
without hypermedia, your HTTP interface is not RESTful
that’s totally fineand sometimes even the only way to do it
(e.g. CouchDB or S3 are never going to be RESTful)
just avoid calling it a "REST API" :)
good hypermedia format example: the Lovefilm API
<?xml  version="1.0"  encoding="utf-­‐8"  standalone="yes"?><search>    <total_results>6</total_results>    <items_per_pag...
ROOM FOR IMPROVEMENT IN    THE LOVEFILM API• Uses   application/xml instead of a custom media type • Once  that is fixed, a...
another great RESTful API: Huddle
<document    xmlns="http://schema.huddle.net/2011/02/"    title="TPS  report  May  2010"    description="relentlessly  mun...
ROOM FOR IMPROVEMENT IN    THE HUDDLE API• Uses     custom rels like “thumb” or “avatar” not defined in the IANA registry (...
API VERSIONING Media Types To The Rescue!
why not api.myservice.com/v1/foo/bar?and then api.myservice.com/v2/foo/bar?
different URLs means different resources!
also, keep bookmarks (by machines) in mind
API VERSION 1GET  /products  HTTP/1.1Host:  acme.comAccept:  application/vnd.com.myservice+xmlHTTP/1.1  200  OKContent-­‐T...
(some years pass...)
API VERSION 2GET  /products  HTTP/1.1Host:  acme.comAccept:  application/vnd.com.myservice.v2+xmlHTTP/1.1  200  OKContent-...
clients can’t upgrade protocol for known URLs!
Also, imagine every install of phpBB or TYPO3 had an API
If the version is in the URL, clients need to regex those
http://sharksforum.org/community/api/v1/threads/102152
http://forum.sharksforum.org/api/v1/threads/102152
that would be fail
or what if another forum software wants the same API?
also would have to use “/v1/” in their URLs
URI based versioning kills interoperability
YOU MIGHT BE WONDERING     Why Exactly Is This Awesome?
THE MERITS OF REST• Easyto evolve: add new          • Easyto implement: build it features or elements without      on top ...
but...
hold on, you say
a plain HTTP-loving service does the job, you say
surely, there is a merit to REST beyond extensibility, you ask
nope
"REST is software design on the scale of decades: everydetail is intended to promote software longevity andindependent evo...
"Most of RESTs constraints are focused on preservingindependent evolvability over time, which is onlymeasurable on the sca...
FURTHER READING•   Ryan Tomayko    How I Explained REST to my Wife    http://tomayko.com/writings/rest-to-my-wife•   Jim W...
BOOKS ON REST•   Jim Webber, Savas Parastatidis, Ian Robinson    REST in Practice    ISBN: 978-0596805821•   Subbu Allamar...
!e End
Questions?
THANK YOU! This was http://joind.in/6642         by @dzuelkeSend me questions or hire us:david.zuelke@bitextender.com
Designing HTTP Interfaces and RESTful Web Services (IPC2012SE 2012-06-05)
Designing HTTP Interfaces and RESTful Web Services (IPC2012SE 2012-06-05)
Designing HTTP Interfaces and RESTful Web Services (IPC2012SE 2012-06-05)
Designing HTTP Interfaces and RESTful Web Services (IPC2012SE 2012-06-05)
Designing HTTP Interfaces and RESTful Web Services (IPC2012SE 2012-06-05)
Designing HTTP Interfaces and RESTful Web Services (IPC2012SE 2012-06-05)
Upcoming SlideShare
Loading in...5
×

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

2,600

Published on

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

Published in: Technology
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total Views
2,600
On Slideshare
0
From Embeds
0
Number of Embeds
1
Actions
Shares
0
Downloads
19
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

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

  1. 1. DESIGNING HTTP INTERFACESAND RESTFUL WEB SERVICES
  2. 2. David Zuelke
  3. 3. David Zülke
  4. 4. http://en.wikipedia.org/wiki/File:München_Panorama.JPG
  5. 5. Founder
  6. 6. Lead Developer
  7. 7. @dzuelke
  8. 8. THE OLDEN DAYS Before REST was En Vogue
  9. 9. http://www.acme.com/index.php?action=zomg&page=lol
  10. 10. along came
  11. 11.  dis is srs SEO bsns
  12. 12. and said
  13. 13. NEIN NEINNEIN NEIN DAS ISTVERBOTEN
  14. 14. at least if they were
  15. 15. so we had to make URLs "SEO friendly"
  16. 16. http://www.acme.com/zomg/lol
  17. 17. and then things got out of control
  18. 18. because nobody really had a clue
  19. 19. http://acme.com/videos/latest/hamburgers
  20. 20. http://acme.com/search/lolcats/pictures/yes/1/200
  21. 21. oh dear…
  22. 22. THE RISE OF WEB SERVICESOhai, Im ur CEO, I canhaz SOAP API plz, today, kthx?
  23. 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="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>
  24. 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="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>
  25. 25. SOAP sucks, said everyone
  26. 26. lets build APIs without the clutter, they said
  27. 27. example: the http://joind.in/ API
  28. 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. 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. 30. Level 0 in the Richardson Maturity Model: Plain old XML over the wire in an RPC fashion
  31. 31. Room for improvement: use one URI for each resource.
  32. 32. That would be Level 1 in Richardsons Maturity Model
  33. 33. Level 0 and Level 1 are a bag of hurt. Do not use them. Ever.
  34. 34. ALONG CAME ROY FIELDING And Gave Us REST
  35. 35. that was awesome
  36. 36. because everyone could say
  37. 37.  I haz REST nao
  38. 38. when in fact
  39. 39. they bloody didn’t
  40. 40. RESTWhat Does That Even Mean?
  41. 41. REpresentational State Transfer
  42. 42. Roy Thomas Fielding: Architectural styles andthe design of network based software architectures.
  43. 43. REST CONSTRAINTS• Client-Server• Stateless• Cacheable• Layered System• Code on Demand (optional)• Uniform Interface
  44. 44. Simple explaination of the Uniform Interface
  45. 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. 46. a web page is not a resource
  47. 47. it is a (complete) representation of a resource
  48. 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:  "http://acme.com/products/1234"    }]
  49. 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="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>
  50. 50. no hypermedia formats yet in those examples!
  51. 51. I will show that in a few minutes
  52. 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="http://acme.com/products/1234">Red  Stapler</a>  (€3.14)</li>        </ul>    </body></html>
  53. 53. VOLUME ONEDesigning an HTTP Interface
  54. 54. FIRST: DEFINE RESOURCES A Good Approach: Structure Your URLs
  55. 55. 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
  56. 56. 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
  57. 57. now heres the ironic part
  58. 58. URLs dont matter once you have a fully RESTful interface
  59. 59. but it’s helpful to think in terms of resources
  60. 60. SECOND: USE RESOURCES CRUD, but not really
  61. 61. 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
  62. 62. ITEM OPERATIONS• http://www.acme.com/products/1234 • GET to retrieve • PUT to update • DELETE to, you guessed it, delete
  63. 63. and remember
  64. 64. dont let the server maintain client state (e.g. cookies)
  65. 65. Now we are at Level 2 in RMM
  66. 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. 67. THE TWITTER APINot RESTful, And Not Even Getting HTTP Right :(
  68. 68. mind you were not even inspecting the RESTfulness
  69. 69. were just looking at Twitters API from an HTTP perspective
  70. 70. STATUSES/SHOW• 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
  71. 71. STATUSES/UPDATE• 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/CaseySoftware/statuses/
  72. 72. STATUSES/DESTROY• 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
  73. 73. STATUSES/RETWEETS• GET http://api.twitter.com/1/statuses/retweets/12345.json• Problems: • Hierarchy is wrong• Better: GET http://twitter.com/statuses/12345/retweets/
  74. 74. STATUSES/RETWEET• 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/
  75. 75. 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
  76. 76. ANGRY GERMAN SUMMARY• Twitters "REST" API sucks, hates HTTP and kills baby kittens.
  77. 77. INTERMISSIONWhats the Biggest Reason for the Success of the Web?
  78. 78. WWW
  79. 79. first data exchange system
  80. 80. planetary scale
  81. 81. why is that possible?
  82. 82. Hyperlinks!
  83. 83. no tight coupling!
  84. 84. loosely coupled by design
  85. 85. no notification infrastructure
  86. 86. HTTP/1.1 404 Not Found
  87. 87. embraces failure
  88. 88. more information != more friction
  89. 89. no limits to scalability
  90. 90. WWW is protocol-centric
  91. 91. VOLUME TWORESTful Services with Hypermedia
  92. 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. 93. HATEOASThe Missing Piece in the Puzzle
  94. 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. 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. 96. (X)HTML and Atom are Hypermedia formats
  97. 97. Or you roll your own...
  98. 98. A CUSTOM MEDIA TYPEGET  /products/1234  HTTP/1.1 Remind clients ofHost:  acme.comAccept:  application/vnd.com.acme.shop+xml Uniform Interface :) re-use Atom forHTTP/1.1  200  OKContent-­‐Type:  application/vnd.come.acme.shop+xml;  charset=utf-­‐8 link relationsAllow:  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> meaning defined in IANA Link Relations list
  99. 99. boom, RMM Level 3
  100. 100. XML is really good for hypermedia formats
  101. 101. (hyperlinks, namespaced attributes, re-use of formats, …)
  102. 102. JSON is more difficult
  103. 103. (no hyperlinks, no namespaces, no element attributes)
  104. 104. XML VERSUS JSON<?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"        }    ]}
  105. 105. also, JSON is hard to evolve without breaking clients
  106. 106. <?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>
  107. 107. <?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>
  108. 108. <?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>
  109. 109. <?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>
  110. 110. <?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>
  111. 111. and hey
  112. 112. without hypermedia, your HTTP interface is not RESTful
  113. 113. that’s totally fineand sometimes even the only way to do it
  114. 114. (e.g. CouchDB or S3 are never going to be RESTful)
  115. 115. just avoid calling it a "REST API" :)
  116. 116. good hypermedia format example: the Lovefilm API
  117. 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="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>
  118. 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. 119. another great RESTful API: Huddle
  120. 120. <document    xmlns="http://schema.huddle.net/2011/02/"    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. 121. ROOM FOR IMPROVEMENT IN THE HUDDLE API• Uses custom rels like “thumb” or “avatar” not defined in the IANA registry (http://www.iana.org/assignments/link-relations) • Risk of collisions and ambiguity; should use something like “http://rels.huddle.net/thumb” 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. 122. API VERSIONING Media Types To The Rescue!
  123. 123. why not api.myservice.com/v1/foo/bar?and then api.myservice.com/v2/foo/bar?
  124. 124. different URLs means different resources!
  125. 125. also, keep bookmarks (by machines) in mind
  126. 126. API VERSION 1GET  /products  HTTP/1.1Host:  acme.comAccept:  application/vnd.com.myservice+xmlHTTP/1.1  200  OKContent-­‐Type:  application/vnd.com.myservice+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>
  127. 127. (some years pass...)
  128. 128. API VERSION 2GET  /products  HTTP/1.1Host:  acme.comAccept:  application/vnd.com.myservice.v2+xmlHTTP/1.1  200  OKContent-­‐Type:  application/vnd.com.myservice.v2+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>        <availability>false</availability>    </product></products>
  129. 129. clients can’t upgrade protocol for known URLs!
  130. 130. Also, imagine every install of phpBB or TYPO3 had an API
  131. 131. If the version is in the URL, clients need to regex those
  132. 132. http://sharksforum.org/community/api/v1/threads/102152
  133. 133. http://forum.sharksforum.org/api/v1/threads/102152
  134. 134. that would be fail
  135. 135. or what if another forum software wants the same API?
  136. 136. also would have to use “/v1/” in their URLs
  137. 137. URI based versioning kills interoperability
  138. 138. YOU MIGHT BE WONDERING Why Exactly Is This Awesome?
  139. 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. 140. but...
  141. 141. hold on, you say
  142. 142. a plain HTTP-loving service does the job, you say
  143. 143. surely, there is a merit to REST beyond extensibility, you ask
  144. 144. nope
  145. 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. 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. 147. 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
  148. 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. 149. !e End
  150. 150. Questions?
  151. 151. THANK YOU! This was http://joind.in/6642 by @dzuelkeSend me questions or hire us:david.zuelke@bitextender.com
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.

×