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

Demystifying the REST API

Demystifying the REST API

Are you confused by REST APIs? Can't tell a PUT from a POST? No idea what a non-idempotent operation is?

Despite their ubiquity, the details of what makes an API RESTful are often lost even on experienced developers. We'll cover the basics of the HTTP protocol that drives most REST services, break down the lingo, and clear up some misconceptions about this powerful and popular methodology.

Samantha Quiñones

January 18, 2014
Tweet

More Decks by Samantha Quiñones

Other Decks in Programming

Transcript

  1. About Me Samantha Quiñones SW Architect & Lead Developer at

    POLITICO.com Follow me: @ieatkillerbees
  2. What is REST? (and why am I talking about it?)

    REpresentational State Transfer An architectural style that describes a set of rules for delivering content over an open network
  3. Nothing is more easy than to reduce this mass to

    one quarter of its bulk. You know that curious cellular matter which constitutes the elementary tissues of vegetable? This substance is found quite pure in many bodies, especially in cotton, which is nothing more than the down of the seeds of the cotton plant. Now cotton, combined with cold nitric acid, become transformed into a substance eminently insoluble, combustible, and explosive. It was first discovered in 1832, by Braconnot, a French chemist, who called it xyloidine. In 1838 another Frenchman, Pelouze, investigated its different properties, and finally, in 1846, Schonbein, professor of chemistry at Bale, proposed its employment for purposes of war. This powder, now called pyroxyle, or fulminating cotton, is prepared with great facility by simply plunging cotton for fifteen minutes in nitric acid, then washing it in water, then drying it, and it is ready for use.
  4. Nothing is more easy than to reduce this mass to

    one quarter of its bulk. You know that curious cellular matter which constitutes the elementary tissues of vegetable? This substance is found quite pure in many bodies, especially in cotton, which is nothing more than the down of the seeds of the cotton plant. Now cotton, combined with cold nitric acid, become transformed into a substance eminently insoluble, combustible, and explosive. It was first discovered in 1832, by Braconnot, a French chemist, who called it xyloidine. In 1838 another Frenchman, Pelouze, investigated its different properties, and finally, in 1846, Schonbein, professor of chemistry at Bale, proposed its employment for purposes of war. This powder, now called pyroxyle, or fulminating cotton, is prepared with great facility by simply plunging cotton for fifteen minutes in nitric acid, then washing it in water, then drying it, and it is ready for use.
  5. Ordo ab chao REST is a set of constraints designed

    to bring order of the chaos of free-form hypermedia The young web was extremely disordered Fielding envisioned the web as a system that could be moulded by carefully applying constraints
  6. Null Style The Null Style describes an empty set of

    constraints There are no boundaries and no structure
  7. Client-Server Architecture The system is divided in to clients and

    servers Servers store hypermedia resources Clients manage the display and caching of resources
  8. Implicit State Requesting the “next” resource in a collection requires

    the server to know what you asked for last This information may need to be shared among many servers in a cluster This information may be lost due to server errors Gief next cat pic pls!
  9. Explicit State The client is better suited to choose what

    state is important Server failures do not cause loss of state Improved performance and reliability Load-balancing becomes trivial Gief cat pic #3427 pls!
  10. Debugging State Stinks All requests contain all the context needed

    to execute them Simplifies debugging Makes traffic “replayable”
  11. Cacheable Requests Transmitting state with each request increases overhead Allowing

    clients to cache responses can drastically reduce the number required requests
  12. Best Parsed By… Resources can carry an expiration time Clients

    can wait until a resource expires before requesting it again
  13. Representations {      name:  “Kitty  McAwesome”,      awesome:

     true,      cute:  “very”,      image_uri:  “http://i.imgur.com/eqTIb.jpg”   }
  14. HATEOAS GET  /events/201   ! 200  OK   <event>  

       <id>201</id>      <name>Summer  Bridge  Party</name>      <organizer>          <name>David  Wildstein</name>          <email>[email protected]</email>          <link  rel=”self”  href=”/organizers/42”  />      </organizer>      <link  rel=”self”  href=”/events/201”  />      <link  rel=”attendees”  href=”/events/201/attendees”  />   </event>
  15. JSON & Hypermedia GET  /events/201   ! 200  OK  

    {      id:  201,      name:  “Summer  Bridge  Party”,      organizer:  {          name:  “David  Wildstein”,          email:  “[email protected]”      }   }  
  16. Hypertext Application Language (HAL) Proposed standard that extends the JSON

    type with hypermedia data application/json+hal Small but growing acceptance
  17. HAL GET  /events/201   ! 200  OK   {  

       “id”:  201,      “name”:  “Summer  Bridge  Party”,      “_links”:  {          “self”:  {  “href”:  “/events/201”  },      },      “_embedded”:  {          “organizer”:  {                “_links”:  {                    “self”:  {  “href”:  “/organizers/42”  }              }      }   }
  18. Layered System Any two layers can only see one another

    Client > Proxy > Load Balancer > Server
  19. Batteries Included Representations can include executable code Allows clients to

    have extended functionality without updating multiple code bases JavaScript, Flash, Java Applets
  20. “A resource (R) is a temporally varying membership function MR(t),

    which for time t maps to a set of entities, or values, which are equivalent.” –Roy Fielding Resources
  21. Resources An abstraction of some entity, or a collection of

    entities, that we can identify by name. http://i.imgur.com/eqTIb.jpg “all accounts created on October 12th” “the most recent 100 tweets containing the string ‘#redwedding’”
  22. Resources On the web, we use Uniform Resource Identifiers http://i.imgur.com/eqTIb.jpg

    Resource named eqTIb.jpg available via HTTP from i.imgur.com
  23. Representations In order to interact with a resource, we use

    a representation Representations contain data and metadata
  24. Representations GET  /accounts/42   ! 200  OK   Content-­‐Type:  application/json+hal

      ! {      account_id:  42,      account_name:  “Samantha  Quiñones”,      account_status:  “awesome”      _links:  {  self:  {  href:  “/accounts/42”  }  }         }
  25. Representations Resources are abstract, representations are concrete Representations are the

    actual bytes that are transferred between clients and servers, including metadata Often called a “file,” “document,” or “entity”
  26. Control Data Control data is extra information used by the

    client and server to coordinate Cache control information Parameters Content-type negotiation
  27. HyperText Transfer Protocol Version 0.9 (1991), Version 1.0 (1996) Current

    Version 1.1 defined by RFC 2616 Nine methods, ~40 response codes
  28. Request-Response Cycle Client opens a connection to a server Client

    sends a request containing a method, a resource, and optionally meta/control data Server responds with a status code and a representation of the requested resource, along with meta/control data
  29. ! $app-­‐>get("/foo/{id}",  function  (Request  $request,  Application  $app,  $id)  {  

           if  (  !  $app['db']-­‐>has($id))  {                  throw  new  HttpNotFoundException();          }   !        return  new  Response($app['db']-­‐>get($id));   });   GET
  30. HEAD, OPTIONS, and TRACE HEAD requests the headers that would

    have been sent with the equivalent GET request OPTIONS requests the HTTP methods that the server supports for a given resource TRACE requests the server echo back the request. This is useful for determining if an intermediate server is altering a requests in flight.
  31. DELETE $app-­‐>delete("/foo/{id}",  function  (Request  $request,  Application  $app,  $id)  {  

           if  (  !  $app['db']-­‐>has($id))  {                  throw  new  HttpNotFoundException();          }   !        $app['db']-­‐>delete($id);   !        return  new  Response("",  Response::HTTP_NO_CONTENT);   });
  32. PUT Asks the server to store a resource at a

    specific URI, overwriting it if it already exists
  33. PUT $app-­‐>put("/foo/{id}",  function  (Request  $request,  Application  $app,  $id)  {  

           if  ($app['db']-­‐>has($id))  {                  $app['db']-­‐>update($id,  $request-­‐>getBody());                  return  new  Response("",  Response::HTTP_OK)          }   !        $app['db']-­‐>insertWithId($id,  $request-­‐>getBody());          return  new  Response("",  Response::HTTP_CREATED);   });
  34. POST Asks the server to store a resource as a

    sub- resource of a specified resource or collection
  35. POST $app-­‐>post("/foo",  function  (Request  $request,  Application  $app)  {    

         $newId  =  $app['db']-­‐>insert($request-­‐>getBody());          $responseData  =  array(                  "_links"  =>  array(                          "self"  =>  array(                                  "href"  =>  "/foo/$newId"                          )                  )          );          return  new  Response($responseData,  Response::HTTP_CREATED);   });  
  36. POST is Versatile Annotate existing resources Posting to a message

    board, mailing list, etc Providing a block of data to a data-handling process Appending to a database
  37. PUT vs POST PUT creates or replaces a resources with

    a known identifier POST creates a sub-resource of an existing resource or collection
  38. Idempotence When the result of an operation remains the same

    no matter how many times the operation is performed, the operation is “idempotent”
  39. Idempotence Safe & Idempotent • GET • TRACE • HEAD

    • OPTIONS Unsafe & Idempotent • PUT • DELETE ! Unsafe & Non-Idempotent • POST • PATCH
  40. DELETE is Idempotent Deleting a resource causes the server to

    return a status code of 204 (NO CONTENT) Subsequent DELETE requests will cause the server to return a status code of 404 (NOT FOUND) How is that idempotent?
  41. Idempotence Refers to Resource State Even though the first DELETE

    request returns a different status code than subsequent requests, the state of that resource (that is, it’s lack of existence) remains the same!
  42. PUT vs POST Redux PUT is idempotent POST is not

    always idempotent, though it can be Use PUT to create or replace resources whose name you already know Use POST to create sub-resources and to append to a collection
  43. PUT vs POST Example PUT  /talks/demystifying-­‐the-­‐rest-­‐api   ! {  

       talk_name:  “Demystifying  the  REST  API”,      speaker:  “Samantha  Quiñones”,      conferences:  []   }  
  44. PUT vs POST Example GET  /talks/demystifying-­‐the-­‐rest-­‐api   ! 200  OK

      {      talk_name:  “Demystifying  the  REST  API”,      speaker:  “Samantha  Quiñones”,      conferences:  []   }  
  45. PUT vs POST Example GET  /talks/demystifying-­‐the-­‐rest-­‐api   ! {  

       talk_name:  “Demystifying  the  REST  API”,      speaker:  “Samantha  Quiñones”,      conferences:  [{conference_name:  “Northeast  PHP”} {conference_name:  “Northeast  PHP”},   {conference_name:  “Northeast  PHP”},   {conference_name:  “Northeast  PHP”},   {conference_name:  “Northeast  PHP”},   {conference_name:  “Northeast  PHP”},   {conference_name:  “Northeast  PHP”},   {conference_name:  “Northeast  PHP”},   {conference_name:  “Northeast  PHP”},   {conference_name:  “Northeast  PHP”},  
  46. PATCH Asks the server to modify a resource Newest method

    Not widely supported (yet) Must be used with caution because of potentially high collision risk
  47. Why PATCH? PUT requires us to send a complete copy

    of the resource, which causes a lot of overhead POST is often used to modify resources, but there is no standard methodology Standards (like JSON Patch) are being developed Patching XML is (partially) supported in RFC 5261
  48. JSON Patch PATCH  /foo   ! 200  OK   [

       {  "op":  "test",  "path":  "/a/b/c",  "value":  "foo"  },    {  "op":  "remove",  "path":  "/a/b/c"  },    {  "op":  "add",  "path":  "/a/b/c",  "value":  [  "foo",  "bar"  ]  },    {  "op":  "replace",  "path":  "/a/b/c",  "value":  42  },    {  "op":  "move",  "from":  "/a/b/c",  "path":  "/a/b/d"  },    {  "op":  "copy",  "from":  "/a/b/d",  "path":  "/a/b/e"  }   ]  
  49. CONNECT Used with proxies that allow for tunneling or protocol

    switching and other things that are both interesting and intensely boring
  50. Status Codes 1xx - Informational Messages 2xx - Success 3xx

    - Redirection 4xx - Client error (“you messed up!”) 5xx - Server error (“I messed up!”)
  51. What happens when you assume… REST makes assumptions safe by

    applying well- established patterns A REST API should be self-documenting so that clients can easily integrate with it
  52. Use response codes everyone understands It’s easier for a client

    to respond to “401 Unauthorized” than “500 Your login has timed out”
  53. Don’t overload POST “When in doubt, use POST” Reconsider your

    application design. Does another method fit better? Are you not really working just with objects and interactions? Is REST the right pattern for your application?
  54. Resources RFC 2616 “Hypertext Transfer Protocol” (http://bit.ly/ LkW6OW) RFC 5789

    “PATCH Method for HTTP” (http://bit.ly/1cFpvtq) JSON HAL Proposal (http://bit.ly/1kJLvgw) RFC 6902 “JSON PATCH” (http://bit.ly/LkWyww) Fielding’s Dissertation (http://bit.ly/1eTY8AI) REST Cookbook (http://restcookbook.com)
  55. PHP Resources HATEOAS for PHP: http://hateoas-php.org/ Well-supported, Symfony-ready HATEOAS library

    REST APIs with Symfony2: The Right Way (http:// williamdurand.fr/2012/08/02/rest-apis-with- symfony2-the-right-way/) Building APIs You Won’t Hate - Phil Sturgeon https://leanpub.com/build-apis-you-wont-hate