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.

Transcript

1. DEMYSTIFYING THE REST API SAMANTHA QUIÑONES
2. About Me Samantha Quiñones SW Architect & Lead Developer at POLITICO.com Follow me: @ieatkillerbees
7. 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
8. ROY FIELDING DESCRIBED THE REST PATTERN IN HIS 2000 DOCTORAL DISSERTATION
9. 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.
10. 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.
12. Apache PHP 5.4 MariaDB Typical Application Design
13. Hopefully… Requirements are met Users are happy Invoices are paid
14. MO’ ENDPOINTS, MO’ PROBLEMS `
16. 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
17. The Early Web Hypertext Data Flash Media Java Applets Cat Pictures
18. The Early Web GIEF CAT PIX PL0X!!1!
19. Null Style The Null Style describes an empty set of constraints There are no boundaries and no structure
20. CLIENT-SERVER ARCHITECTURE CONSTRAINT #1
21. Client-Server Architecture The system is divided in to clients and servers Servers store hypermedia resources Clients manage the display and caching of resources
22. PORTABILITY PREMIUM INFINITE DIVERSITY IN INFINITE CLIENTS
23. STATELESSNESS CONSTRAINT #2
24. 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!
25. 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!
26. Debugging State Stinks All requests contain all the context needed to execute them Simplifies debugging Makes traffic “replayable”
27. CACHE-ABILITY CONSTRAINT #3
28. Cacheable Requests Transmitting state with each request increases overhead Allowing clients to cache responses can drastically reduce the number required requests
29. Best Parsed By… Resources can carry an expiration time Clients can wait until a resource expires before requesting it again
30. UNIFORM INTERFACE CONSTRAINT #4
31. Resources Resources are abstractions of data with a globally unique identifier http://i.imgur.com/eqTIb.jpg
32. Representations {      name:  “Kitty  McAwesome”,      awesome:  true,      cute:  “very”,      image_uri:  “http://i.imgur.com/eqTIb.jpg”   }
33. Self-Contained Requests GET  /eqTIb.jpg  HTTP/1.1   Host:  i.imgur.com   If-­‐Modified-­‐Since:  Fri,  02  Dec  2011  19:47:21  GMT
34. HATEOAS Hypermedia As The Engine Of Application State
36. HATEOAS GET  /events/201   ! 200  OK   <event>      <id>201</id>      <name>Summer  Bridge  Party</name>      <organizer>          <name>David  Wildstein</name>          <email>david.wildstein@gmail.com</email>          <link  rel=”self”  href=”/organizers/42”  />      </organizer>      <link  rel=”self”  href=”/events/201”  />      <link  rel=”attendees”  href=”/events/201/attendees”  />   </event>
37. Hypermedia Types HTML XML CSS XHTML Atom
38. JSON IS NOT A HYPERMEDIA TYPE
40. JSON & Hypermedia GET  /events/201   ! 200  OK   {      id:  201,      name:  “Summer  Bridge  Party”,      organizer:  {          name:  “David  Wildstein”,          email:  “david.wildstein@gmail.com”      }   }  
41. JSON Hyper-Schema Extension of json-schema that allows for hypermedia descriptions http://json-schema.org
42. Hypertext Application Language (HAL) Proposed standard that extends the JSON type with hypermedia data application/json+hal Small but growing acceptance
43. HAL GET  /events/201   ! 200  OK   {      “id”:  201,      “name”:  “Summer  Bridge  Party”,      “_links”:  {          “self”:  {  “href”:  “/events/201”  },      },      “_embedded”:  {          “organizer”:  {                “_links”:  {                    “self”:  {  “href”:  “/organizers/42”  }              }      }   }
44. CONSTRAINT LAYERING CONSTRAINT #5
45. Layered System Any two layers can only see one another Client > Proxy > Load Balancer > Server
46. CODE-ON- DEMAND CONSTRAINT #6
47. Batteries Included Representations can include executable code Allows clients to have extended functionality without updating multiple code bases JavaScript, Flash, Java Applets
48. REPRESENTATIONS & RESOURCES UNDERSTANDING THE PARTS
49. Elements of Rest Resources Representations Meta Data Control Data
50. “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
52. 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’”
53. 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
54. Representations In order to interact with a resource, we use a representation Representations contain data and metadata
55. 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”  }  }         }
56. 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”
57. Control Data Control data is extra information used by the client and server to coordinate Cache control information Parameters Content-type negotiation
58. What is REST? Resource-oriented DRY Cache-ready Stateless
59. HTTP HYPERTEXT TRANSFER PROTOCOL
60. HyperText Transfer Protocol Version 0.9 (1991), Version 1.0 (1996) Current Version 1.1 defined by RFC 2616 Nine methods, ~40 response codes
61. 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
62. Methods “Safe” methods: GET, HEAD, TRACE, OPTIONS “Unsafe” methods: PUT, POST, DELETE, PATCH “Control” method: CONNECT
63. GET Requests a representation of a resource Safe method without side effects
64. ! $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
65. 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.
66. DELETE Delete a resource
67. 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);   });
68. PUT Asks the server to store a resource at a specific URI, overwriting it if it already exists
69. 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);   });
70. POST Asks the server to store a resource as a sub- resource of a specified resource or collection
71. 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);   });  
72. 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
73. PUT vs POST PUT creates or replaces a resources with a known identifier POST creates a sub-resource of an existing resource or collection
74. Idempotence When the result of an operation remains the same no matter how many times the operation is performed, the operation is “idempotent”
75. Idempotence Safe & Idempotent • GET • TRACE • HEAD • OPTIONS Unsafe & Idempotent • PUT • DELETE ! Unsafe & Non-Idempotent • POST • PATCH
76. 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?
77. 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!
78. 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
79. PUT vs POST Example PUT  /talks/demystifying-­‐the-­‐rest-­‐api   ! {      talk_name:  “Demystifying  the  REST  API”,      speaker:  “Samantha  Quiñones”,      conferences:  []   }  
80. PUT vs POST Example GET  /talks/demystifying-­‐the-­‐rest-­‐api   ! 200  OK   {      talk_name:  “Demystifying  the  REST  API”,      speaker:  “Samantha  Quiñones”,      conferences:  []   }  
81. PUT vs POST Example POST  /talks/demystifying-­‐the-­‐rest-­‐api/conferences   ! {conference_name:  “Northeast  PHP”}  
82. 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”},  
83. 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
84. 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
85. 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"  }   ]  
86. CONNECT Used with proxies that allow for tunneling or protocol switching and other things that are both interesting and intensely boring
87. Status Codes 1xx - Informational Messages 2xx - Success 3xx - Redirection 4xx - Client error (“you messed up!”) 5xx - Server error (“I messed up!”)
88. BUILDING GREAT APIS THOUGHTS, TIPS, AND RESOURCES
89. 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
90. Respect safe methods GET should never cause side-effects! GET /events/delete?id=201
91. Use response codes everyone understands It’s easier for a client to respond to “401 Unauthorized” than “500 Your login has timed out”
92. 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?
93. 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)
94. 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
95. Feedback & Contact Joind.in https://joind.in/11470 Twitter: @ieatkillerbees Email: samantha@tembies.com