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
   

   View Slide

2. About Me
   Samantha Quiñones
   
   SW Architect & Lead Developer at POLITICO.com
   
   Follow me: @ieatkillerbees
   

   View Slide

3. View Slide

4. View Slide

5. View Slide

6. View Slide

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
   

   View Slide

8. ROY FIELDING
   DESCRIBED THE REST PATTERN IN HIS 2000 DOCTORAL DISSERTATION
   

   View Slide

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.
   

   View Slide

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.
    

    View Slide

11. View Slide

12. Apache
    PHP
    5.4
    MariaDB
    Typical Application Design
    

    View Slide

13. Hopefully…
    Requirements are met
    
    Users are happy
    
    Invoices are paid
    

    View Slide

14. MO’ ENDPOINTS, MO’ PROBLEMS
    `
    

    View Slide

15. View Slide

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
    

    View Slide

17. The Early Web
    Hypertext
    Data
    Flash
    Media
    Java Applets
    Cat Pictures
    

    View Slide

18. The Early Web
    GIEF CAT PIX
    PL0X!!1!
    

    View Slide

19. Null Style
    The Null Style describes an
    empty set of constraints
    
    There are no boundaries
    and no structure
    

    View Slide

20. CLIENT-SERVER
    ARCHITECTURE
    CONSTRAINT #1
    

    View Slide

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
    

    View Slide

22. PORTABILITY PREMIUM
    INFINITE DIVERSITY IN INFINITE CLIENTS
    

    View Slide

23. STATELESSNESS
    CONSTRAINT #2
    

    View Slide

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!
    

    View Slide

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!
    

    View Slide

26. Debugging State Stinks
    All requests contain all the context needed to
    execute them
    
    Simplifies debugging
    
    Makes traffic “replayable”
    

    View Slide

27. CACHE-ABILITY
    CONSTRAINT #3
    

    View Slide

28. Cacheable Requests
    Transmitting state with each request increases
    overhead
    
    Allowing clients to cache responses can drastically
    reduce the number required requests
    

    View Slide

29. Best Parsed By…
    Resources can carry an
    expiration time
    
    Clients can wait until a
    resource expires before
    requesting it again
    

    View Slide

30. UNIFORM
    INTERFACE
    CONSTRAINT #4
    

    View Slide

31. Resources
    Resources are abstractions
    of data with a globally
    unique identifier
    
    http://i.imgur.com/eqTIb.jpg
    

    View Slide

32. Representations
    {  
       name:  “Kitty  McAwesome”,  
       awesome:  true,  
       cute:  “very”,  
       image_uri:  “http://i.imgur.com/eqTIb.jpg”  
    }
    

    View Slide

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
    

    View Slide

34. HATEOAS
    Hypermedia
    
    As
    
    The
    
    Engine
    
    Of
    
    Application
    
    State
    

    View Slide

35. View Slide

36. HATEOAS
    GET  /events/201  
    !
    200  OK  
     
       201  
       Summer  Bridge  Party  
         
           David  Wildstein  
           david.wildstein@gmail.com  
             
         
         
         
    
    

    View Slide

37. Hypermedia Types
    HTML
    
    XML
    
    CSS
    
    XHTML
    
    Atom
    

    View Slide

38. JSON IS NOT A
    HYPERMEDIA TYPE
    

    View Slide

39. View Slide

40. JSON & Hypermedia
    GET  /events/201  
    !
    200  OK  
    {  
       id:  201,  
       name:  “Summer  Bridge  Party”,  
       organizer:  {  
           name:  “David  Wildstein”,  
           email:  “david.wildstein@gmail.com”  
       }  
    }  
    

    View Slide

41. JSON Hyper-Schema
    Extension of json-schema that allows for
    hypermedia descriptions
    
    http://json-schema.org
    

    View Slide

42. Hypertext Application
    Language (HAL)
    Proposed standard that extends the JSON type
    with hypermedia data
    
    application/json+hal
    
    Small but growing acceptance
    

    View Slide

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”  }  
               }  
       }  
    }
    

    View Slide

44. CONSTRAINT
    LAYERING
    CONSTRAINT #5
    

    View Slide

45. Layered System
    Any two layers can only see one another
    
    Client > Proxy > Load Balancer > Server
    

    View Slide

46. CODE-ON-
    DEMAND
    CONSTRAINT #6
    

    View Slide

47. Batteries Included
    Representations can include executable code
    
    Allows clients to have extended functionality
    without updating multiple code bases
    
    JavaScript, Flash, Java Applets
    

    View Slide

48. REPRESENTATIONS
    & RESOURCES
    UNDERSTANDING THE PARTS
    

    View Slide

49. Elements of Rest
    Resources
    
    Representations
    
    Meta Data
    
    Control Data
    

    View Slide

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
    

    View Slide

51. View Slide

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’”
    

    View Slide

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
    

    View Slide

54. Representations
    In order to interact with a resource, we use a
    representation
    
    Representations contain data and metadata
    

    View Slide

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”  }  }        
    }
    

    View Slide

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”
    

    View Slide

57. Control Data
    Control data is extra information used by the client
    and server to coordinate
    
    Cache control information
    
    Parameters
    
    Content-type negotiation
    

    View Slide

58. What is REST?
    Resource-oriented
    
    DRY
    
    Cache-ready
    
    Stateless
    

    View Slide

59. HTTP
    HYPERTEXT TRANSFER
    PROTOCOL
    

    View Slide

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
    

    View Slide

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
    

    View Slide

62. Methods
    “Safe” methods: GET, HEAD, TRACE, OPTIONS
    
    “Unsafe” methods: PUT, POST, DELETE, PATCH
    
    “Control” method: CONNECT
    

    View Slide

63. GET
    Requests a representation of a resource
    
    Safe method without side effects
    

    View Slide

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
    

    View Slide

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.
    

    View Slide

66. DELETE
    Delete a resource
    

    View Slide

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);  
    });
    

    View Slide

68. PUT
    Asks the server to store a resource at a specific
    URI, overwriting it if it already exists
    

    View Slide

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);  
    });
    

    View Slide

70. POST
    Asks the server to store a resource as a sub-
    resource of a specified resource or collection
    

    View Slide

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);  
    });  
    

    View Slide

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
    

    View Slide

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
    

    View Slide

74. Idempotence
    When the result of an operation remains the same
    no matter how many times the operation is
    performed, the operation is “idempotent”
    

    View Slide

75. Idempotence
    Safe & Idempotent
    • GET
    
    • TRACE
    
    • HEAD
    
    • OPTIONS
    Unsafe & Idempotent
    • PUT
    
    • DELETE
    
    !
    Unsafe & Non-Idempotent
    • POST
    
    • PATCH
    
    

    View Slide

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?
    

    View Slide

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!
    

    View Slide

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
    

    View Slide

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

    View Slide

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

    View Slide

81. PUT vs POST Example
    POST  /talks/demystifying-­‐the-­‐rest-­‐api/conferences  
    !
    {conference_name:  “Northeast  PHP”}  
    

    View Slide

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”},  
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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"  }  
    ]  
    

    View Slide

86. CONNECT
    Used with proxies that allow for tunneling or
    protocol switching and other things that are both
    interesting and intensely boring
    

    View Slide

87. Status Codes
    1xx - Informational Messages
    
    2xx - Success
    
    3xx - Redirection
    
    4xx - Client error (“you messed up!”)
    
    5xx - Server error (“I messed up!”)
    

    View Slide

88. BUILDING
    GREAT APIS
    THOUGHTS, TIPS, AND
    RESOURCES
    

    View Slide

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
    

    View Slide

90. Respect safe methods
    GET should never cause side-effects!
    
    GET /events/delete?id=201
    

    View Slide

91. Use response codes
    everyone understands
    It’s easier for a client to respond to “401
    Unauthorized” than “500 Your login has timed out”
    

    View Slide

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?
    

    View Slide

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)
    

    View Slide

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
    

    View Slide

95. Feedback & Contact
    Joind.in https://joind.in/11470
    
    Twitter: @ieatkillerbees
    
    Email: samantha@tembies.com
    

    View Slide