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. DEMYSTIFYING THE REST API
    SAMANTHA QUIÑONES

    View full-size slide

  2. About Me
    Samantha Quiñones

    SW Architect & Lead Developer at POLITICO.com

    Follow me: @ieatkillerbees

    View full-size slide

  3. 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 full-size slide

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

    View full-size slide

  5. 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 full-size slide

  6. 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 full-size slide

  7. Apache
    PHP
    5.4
    MariaDB
    Typical Application Design

    View full-size slide

  8. Hopefully…
    Requirements are met

    Users are happy

    Invoices are paid

    View full-size slide

  9. MO’ ENDPOINTS, MO’ PROBLEMS
    `

    View full-size slide

  10. 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 full-size slide

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

    View full-size slide

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

    View full-size slide

  13. Null Style
    The Null Style describes an
    empty set of constraints

    There are no boundaries
    and no structure

    View full-size slide

  14. CLIENT-SERVER
    ARCHITECTURE
    CONSTRAINT #1

    View full-size slide

  15. 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 full-size slide

  16. PORTABILITY PREMIUM
    INFINITE DIVERSITY IN INFINITE CLIENTS

    View full-size slide

  17. STATELESSNESS
    CONSTRAINT #2

    View full-size slide

  18. 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 full-size slide

  19. 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 full-size slide

  20. Debugging State Stinks
    All requests contain all the context needed to
    execute them

    Simplifies debugging

    Makes traffic “replayable”

    View full-size slide

  21. CACHE-ABILITY
    CONSTRAINT #3

    View full-size slide

  22. Cacheable Requests
    Transmitting state with each request increases
    overhead

    Allowing clients to cache responses can drastically
    reduce the number required requests

    View full-size slide

  23. Best Parsed By…
    Resources can carry an
    expiration time

    Clients can wait until a
    resource expires before
    requesting it again

    View full-size slide

  24. UNIFORM
    INTERFACE
    CONSTRAINT #4

    View full-size slide

  25. Resources
    Resources are abstractions
    of data with a globally
    unique identifier

    http://i.imgur.com/eqTIb.jpg

    View full-size slide

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

    View full-size slide

  27. 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 full-size slide

  28. HATEOAS
    Hypermedia

    As

    The

    Engine

    Of

    Application

    State

    View full-size slide

  29. HATEOAS
    GET  /events/201  
    !
    200  OK  
     
       201  
       Summer  Bridge  Party  
         
           David  Wildstein  
           [email protected]  
             
         
         
         

    View full-size slide

  30. Hypermedia Types
    HTML

    XML

    CSS

    XHTML

    Atom

    View full-size slide

  31. JSON IS NOT A
    HYPERMEDIA TYPE

    View full-size slide

  32. JSON & Hypermedia
    GET  /events/201  
    !
    200  OK  
    {  
       id:  201,  
       name:  “Summer  Bridge  Party”,  
       organizer:  {  
           name:  “David  Wildstein”,  
           email:  “[email protected]”  
       }  
    }  

    View full-size slide

  33. JSON Hyper-Schema
    Extension of json-schema that allows for
    hypermedia descriptions

    http://json-schema.org

    View full-size slide

  34. Hypertext Application
    Language (HAL)
    Proposed standard that extends the JSON type
    with hypermedia data

    application/json+hal

    Small but growing acceptance

    View full-size slide

  35. 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 full-size slide

  36. CONSTRAINT
    LAYERING
    CONSTRAINT #5

    View full-size slide

  37. Layered System
    Any two layers can only see one another

    Client > Proxy > Load Balancer > Server

    View full-size slide

  38. CODE-ON-
    DEMAND
    CONSTRAINT #6

    View full-size slide

  39. Batteries Included
    Representations can include executable code

    Allows clients to have extended functionality
    without updating multiple code bases

    JavaScript, Flash, Java Applets

    View full-size slide

  40. REPRESENTATIONS
    & RESOURCES
    UNDERSTANDING THE PARTS

    View full-size slide

  41. Elements of Rest
    Resources

    Representations

    Meta Data

    Control Data

    View full-size slide

  42. “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 full-size slide

  43. 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 full-size slide

  44. 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 full-size slide

  45. Representations
    In order to interact with a resource, we use a
    representation

    Representations contain data and metadata

    View full-size slide

  46. 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 full-size slide

  47. 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 full-size slide

  48. Control Data
    Control data is extra information used by the client
    and server to coordinate

    Cache control information

    Parameters

    Content-type negotiation

    View full-size slide

  49. What is REST?
    Resource-oriented

    DRY

    Cache-ready

    Stateless

    View full-size slide

  50. HTTP
    HYPERTEXT TRANSFER
    PROTOCOL

    View full-size slide

  51. 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 full-size slide

  52. 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 full-size slide

  53. Methods
    “Safe” methods: GET, HEAD, TRACE, OPTIONS

    “Unsafe” methods: PUT, POST, DELETE, PATCH

    “Control” method: CONNECT

    View full-size slide

  54. GET
    Requests a representation of a resource

    Safe method without side effects

    View full-size slide

  55. !
    $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 full-size slide

  56. 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 full-size slide

  57. DELETE
    Delete a resource

    View full-size slide

  58. 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 full-size slide

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

    View full-size slide

  60. 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 full-size slide

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

    View full-size slide

  62. 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 full-size slide

  63. 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 full-size slide

  64. 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 full-size slide

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

    View full-size slide

  66. Idempotence
    Safe & Idempotent
    • GET

    • TRACE

    • HEAD

    • OPTIONS
    Unsafe & Idempotent
    • PUT

    • DELETE

    !
    Unsafe & Non-Idempotent
    • POST

    • PATCH

    View full-size slide

  67. 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 full-size slide

  68. 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 full-size slide

  69. 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 full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  73. 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 full-size slide

  74. 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 full-size slide

  75. 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 full-size slide

  76. 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 full-size slide

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

    View full-size slide

  78. Status Codes
    1xx - Informational Messages

    2xx - Success

    3xx - Redirection

    4xx - Client error (“you messed up!”)

    5xx - Server error (“I messed up!”)

    View full-size slide

  79. BUILDING
    GREAT APIS
    THOUGHTS, TIPS, AND
    RESOURCES

    View full-size slide

  80. 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 full-size slide

  81. Respect safe methods
    GET should never cause side-effects!

    GET /events/delete?id=201

    View full-size slide

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

    View full-size slide

  83. 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 full-size slide

  84. 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 full-size slide

  85. 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 full-size slide

  86. Feedback & Contact
    Joind.in https://joind.in/11470

    Twitter: @ieatkillerbees

    Email: [email protected]

    View full-size slide