Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Designing HTTP Interfaces and RESTful Web Services

Designing HTTP Interfaces and RESTful Web Services

Presentation at PHP Australia conference in Sydney, Australia.

David Zuelke

March 13, 2015
Tweet

More Decks by David Zuelke

Other Decks in Programming

Transcript

  1. DESIGNING HTTP INTERFACES
    AND RESTFUL WEB SERVICES

    View full-size slide

  2. David Zuelke

    View full-size slide

  3. THE OLDEN DAYS
    Before REST was En Vogue

    View full-size slide

  4. http://www.acme.com/index.php?action=zomg&page=lol

    View full-size slide

  5. K dis
    is srs SEO

    View full-size slide

  6. NEIN NEIN
    NEIN NEIN
    DAS IST
    VERBOTEN

    View full-size slide

  7. at least if they were

    View full-size slide

  8. so we had to make URLs "SEO friendly"

    View full-size slide

  9. http://www.acme.com/zomg/lol

    View full-size slide

  10. and then things got out of control

    View full-size slide

  11. because nobody really had a clue

    View full-size slide

  12. http://acme.com/videos/latest/hamburgers

    View full-size slide

  13. http://acme.com/search/lolcats/pictures/yes/1/200

    View full-size slide

  14. THE RISE OF WEB SERVICES
    Ohai, I'm ur CEO, I canhaz SOAP API plz, today, kthx?

    View full-size slide

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

    HTTP/1.1  200  OK  
    Content-­‐Type:  text/xml;  charset=utf-­‐8  
     
     
         
             
                 
                   123456  
                   Red  Stapler  
                   3.14  
                 
             
         

    View full-size slide

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

    HTTP/1.1  500  Internal  Service  Error  
    Content-­‐Type:  text/xml;  charset=utf-­‐8  
     
     
         
             
               SOAP-­‐ENV:Server  
               Unknown  Product    
             
         

    View full-size slide

  17. SOAP sucks, said everyone

    View full-size slide

  18. let's build APIs without the clutter, they said

    View full-size slide

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

    View full-size slide

  20. POST  /api/talk  HTTP/1.1  
    Host:  joind.in  
    Content-­‐Type:  text/xml;  charset=utf-­‐8  
     
     
                     
                                   Chuck  Norris  
                                   roundhousekick  
                     
                     
                                   42  
                     

    HTTP/1.1  200  OK  
    Content-­‐Type:  text/xml;  charset=utf-­‐8  
     
     
       
        My  Test  Talk  
        This  is  a  sample  talk  description  
        42  
       

    View full-size slide

  21. 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)

    View full-size slide

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

    View full-size slide

  23. Room for improvement: use one URI for each resource
    “ “

    View full-size slide

  24. That would be Level 1 in Richardson's Maturity Model

    View full-size slide

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

    View full-size slide

  26. ALONG CAME ROY FIELDING
    And Gave Us REST

    View full-size slide

  27. that was awesome

    View full-size slide

  28. because everyone could say

    View full-size slide

  29. J I haz REST nao

    View full-size slide

  30. when in fact

    View full-size slide

  31. they absolutely didn’t

    View full-size slide

  32. REST
    What Does That Even Mean?

    View full-size slide

  33. REpresentational State Transfer

    View full-size slide

  34. Roy Thomas Fielding: Architectural styles and
    the design of network based software architectures.

    View full-size slide

  35. • Client-Server
    • Stateless
    • Cacheable
    • Layered System
    • Code on Demand (optional)
    • Uniform Interface
    REST CONSTRAINTS

    View full-size slide

  36. • 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
    UNIFORM INTERFACE

    View full-size slide

  37. a web page is not a resource

    View full-size slide

  38. it is a (complete) representation of a resource

    View full-size slide

  39. 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"  
       }  
    ]
    GETTING JSON BACK

    View full-size slide

  40. 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  
     
     
         
           Red  Stapler  
           3.14  
         

    GETTING XML BACK

    View full-size slide

  41. but those are not hypermedia formats!

    View full-size slide

  42. (more on that a bit later)

    View full-size slide

  43. 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  
     
         
             
           ACME  Inc.  Products  
         
         
           Our  Incredible  Products  
             
               Red  Stapler  (€3.14)  
             
         

    AND FINALLY, HTML

    View full-size slide

  44. VOLUME ONE
    Designing an HTTP Interface

    View full-size slide

  45. FIRST: DEFINE RESOURCES
    A Good Approach: Structure Your URLs

    View full-size slide

  46. "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
    err...?
    photo or
    product ID?
    new what?

    View full-size slide

  47. "GOOD URLS"
    • http://www.acme.com/products/
    • http://www.acme.com/products/?filter=cats&sort=desc
    • http://www.acme.com/products/1234
    • http://www.acme.com/products/1234/photos/
    • http://www.acme.com/products/1234/photos/?sort=latest
    • http://www.acme.com/products/1234/photos/5678
    a list of products
    filtering is a query
    a single product
    all photos

    View full-size slide

  48. now here's the ironic part

    View full-size slide

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

    View full-size slide

  50. but it’s helpful to think in terms of resources

    View full-size slide

  51. SECOND: USE RESOURCES
    CRUD, but not really

    View full-size slide

  52. 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

    View full-size slide

  53. ITEM OPERATIONS
    • http://www.acme.com/products/1234
    • GET to retrieve
    • PUT to update
    • DELETE to, you guessed it, delete

    View full-size slide

  54. Now we are at Level 2 in RMM

    View full-size slide

  55. 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

    View full-size slide

  56. THE TWITTER (V1) API
    Not RESTful, And Not Even Getting HTTP Right :(

    View full-size slide

  57. mind you we're not even inspecting the RESTfulness

    View full-size slide

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

    View full-size slide

  59. CURRENT STATE
    • GET http://api.twitter.com/1/statuses/show/12345.json
    • POST http://api.twitter.com/1/statuses/update.json
    • DELETE http://api.twitter.com/1/statuses/destroy/12345.json
    • GET http://api.twitter.com/1/statuses/retweets/12345.json
    • PUT http://api.twitter.com/1/statuses/retweet/12345.json
    Doesn’t allow Accept header
    Why a PUT?
    Why the difference?
    Posts to
    auth’d
    user!
    “DELETE destroy”, RPC much?

    View full-size slide

  60. COULD BE SO MUCH SIMPLER
    • http://twitter.com/username/statuses/
    • POST to create a new tweet
    • http://twitter.com/username/statuses/12345
    • DELETE deletes (PUT could be used for updates)
    • http://twitter.com/username/statuses/12345/retweets/
    • POST creates a new retweet

    View full-size slide

  61. INTERMISSION
    What's the Biggest Reason for the Success of the Web?

    View full-size slide

  62. first information exchange system

    View full-size slide

  63. planetary scale

    View full-size slide

  64. why is that possible?

    View full-size slide

  65. no tight coupling!

    View full-size slide

  66. loosely coupled by design

    View full-size slide

  67. no notification infrastructure

    View full-size slide

  68. HTTP/1.1 404 Not Found

    View full-size slide

  69. embraces failure

    View full-size slide

  70. more information != more friction

    View full-size slide

  71. no limits to scalability

    View full-size slide

  72. WWW is protocol-centric

    View full-size slide

  73. VOLUME TWO
    RESTful Services with Hypermedia

    View full-size slide

  74. 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")
    "without you I am nothing"

    View full-size slide

  75. HATEOAS
    The Missing Piece in the Puzzle

    View full-size slide

  76. 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?

    View full-size slide

  77. 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!

    View full-size slide

  78. (X)HTML and Atom are Hypermedia formats

    View full-size slide

  79. Or you roll your own...

    View full-size slide

  80. GET  /products/1234  HTTP/1.1  
    Host:  acme.com  
    Accept:  application/vnd.com.acme.shop+xml
    HTTP/1.1  200  OK  
    Content-­‐Type:  application/vnd.come.acme.shop+xml;  charset=utf-­‐8  
    Allow:  GET,  PUT,  DELETE  
     
     
       1234  
       Red  Stapler  
       3.14

                                 href="http://acme.com/products/1234/payment"/>  

    re-use Atom for

    link relations
    meaning defined in IANA Link Relations list
    A CUSTOM MEDIA TYPE
    Remind clients of
    Uniform Interface :)

    View full-size slide

  81. boom, RMM Level 3

    View full-size slide

  82. XML is really good for hypermedia formats

    View full-size slide

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

    View full-size slide

  84. JSON is more difficult

    View full-size slide

  85. (no hyperlinks, no namespaces, no element attributes)

    View full-size slide

  86.  
     
       1234  
       Red  Stapler  
                                 href="http://acme.com/products/1234/payment"/>  
       3.14


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

    View full-size slide

  87.  
     
       1234  
       Red  Stapler  
                                 href="http://acme.com/products/1234/payment"/>  
       3.14


    {  
       id:  1234,  
       name:  "Red  Stapler",  
       links:  [  
           {  
               rel:  "payment",  
               type:  "application/vnd.com.acme.shop+json",  
               href:  "http://acme.com/products/1234/payment"  
           }  
       ],  
       price:  {  
           amount:  3.14,  
           currency:  "EUR"  
       }  
    }
    XML VERSUS JSON
    Content (“node value”) still the same
    Float becomes object, stuff breaks

    View full-size slide

  88. JSON is difficult to evolve without breaking clients

    View full-size slide

  89. XML’s document model is built for extensibility

    View full-size slide

  90.  
     
         
           Bacon  
           5.99  
         
     

    View full-size slide

  91.  
     
         
           Bacon  
           5.99  
           OMNOMNOM  Bacon  
         
     

    View full-size slide

  92.  
     
         
           Bacon  
           5.99  
         
     

    View full-size slide

  93.  
     
         
           Bacon  
           5.99  
           4.49  
         
     

    View full-size slide

  94.  
     
         
           Bacon  
           Speck  
           5.99  
           4.49  
         

    View full-size slide

  95.  
     
         
           Bacon  
           Speck  
           5.99  
             
         

    View full-size slide

  96. without Hypermedia, your HTTP interface is not RESTful

    View full-size slide

  97. that’s totally fine

    and sometimes even the only way to do it

    View full-size slide

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

    View full-size slide

  99. just avoid calling it a "REST API" :)

    View full-size slide

  100. $next  =  'http://shop.com/search?q=sharks';

    while($next)  {

           $doc  =  DOMDocument::loadXML(file_get_contents($url));

           $xpath  =  new  DOMXPath($doc);

           foreach($xpath-­‐>query('/searchResult/product')  as  $product)  {

                   MyMagicDatabase::import($product);

           }

           $next  =  $xpath-­‐>evaluate('/searchResult/link[@rel="next"]/@href');

    }
    WITH HATEOAS, CLIENTS
    BECOME STATE MACHINES
     
             
             
           ...  
           ...  
           ...  

    View full-size slide

  101. good Hypermedia format example: the Lovefilm API

    View full-size slide

  102.  
     
       6  
       1  
       1  
                       rel="self"  title="self"/>  
                       rel="next"  title="next"/>  
                       rel="last"  title="last"/>  
         
           true  
           2003-­‐09-­‐12  
             
           http://openapi.lovefilm.com/catalog/title/59643  
           false  
           574  
           4  
             
             
             
             
             
                               rel="http://schemas.lovefilm.com/synopsis"  title="synopsis"/>  
                               rel="http://schemas.lovefilm.com/reviews"  title="reviews"/>  
                               rel="alternate"  title="web  page"/>  
         

    View full-size slide

  103. 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

    View full-size slide

  104. another great RESTful API: Huddle

    View full-size slide

  105.    xmlns="http://schema.huddle.net/2011/02/"  
       title="TPS  report  May  2010"  
       description="relentlessly  mundane  and  enervating.">  
         
         
         
         
         
         
         
         
         
         
         
         
             
             
             
         
         
         
             
             
             
         
         
       19475  
         
       98  
       2007-­‐10-­‐10T09:02:17Z  
       2011-­‐10-­‐10T09:02:17Z  
       Complete  
       9  

    View full-size slide

  106. 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

    View full-size slide

  107. API VERSIONING
    Media Types To The Rescue!

    View full-size slide

  108. why not api.myservice.com/v1/foo/bar?
    and then api.myservice.com/v2/foo/bar?

    View full-size slide

  109. different URLs means different resources!

    View full-size slide

  110. also, keep bookmarks (by machines) in mind

    View full-size slide

  111. GET  /products/1234  HTTP/1.1  
    Host:  acme.com  
    Accept:  application/vnd.com.myservice+xml
    HTTP/1.1  200  OK  
    Content-­‐Type:  application/vnd.com.myservice+xml;  charset=utf-­‐8  
    Allow:  GET,  PUT,  DELETE  
     
                     id="1234"  xl:type="simple"  xl:href="http://acme.com/products/1234">  
       Red  Stapler  
       3.14  

    API VERSION 1

    View full-size slide

  112. (item sells out...)

    View full-size slide

  113. GET  /products/1234  HTTP/1.1  
    Host:  acme.com  
    Accept:  application/vnd.com.myservice+xml
    HTTP/1.1  410  Gone  
    Content-­‐Type:  application/vnd.com.myservice+xml;  charset=utf-­‐8
    API VERSION 1

    View full-size slide

  114. API now offers a new protocol version
    with availability indicators (breaking change!)

    View full-size slide

  115. GET  /products/1234  HTTP/1.1  
    Host:  acme.com  
    Accept:  application/vnd.com.myservice.v2+xml
    HTTP/1.1  200  OK  
    Content-­‐Type:  application/vnd.com.myservice.v2+xml;  charset=utf-­‐8  
    Allow:  GET,  PUT,  DELETE  
     
                     id="1234"  xl:type="simple"  xl:href="http://acme.com/products/1234">  
       Red  Stapler  
       3.14  
       false  

    API VERSION 2

    View full-size slide

  116. clients can’t upgrade protocol for known URLs!

    View full-size slide

  117. Also, imagine every install of phpBB or Drupal had an API

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  121. that would be fail

    View full-size slide

  122. or what if another forum software wants the same API?

    View full-size slide

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

    View full-size slide

  124. URI based versioning kills interoperability

    View full-size slide

  125. YOU MIGHT BE WONDERING
    Why Exactly Is This Awesome?

    View full-size slide

  126. 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

    View full-size slide

  127. hold on, you say

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  130. "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

    View full-size slide

  131. "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

    View full-size slide

  132. FURTHER READING
    • Leonard Richardson, Mike Amundsen, Sam Ruby

    RESTful Web APIs

    ISBN: 978-1449358068
    • 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

    View full-size slide

  133. MORE 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

    View full-size slide

  134. RESTFUL
    WEB SERVICES
    Thanks for listening! Contact:
    @dzuelke & [email protected].
    rate my talk
    on joind.in!

    View full-size slide