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

REST vs GraphQL: The What, How and Why

REST vs GraphQL: The What, How and Why

What they are, how they differ and when to use each, or both.

Marco Petersen

November 07, 2017
Tweet

More Decks by Marco Petersen

Other Decks in Programming

Transcript

  1. REST vs GraphQL
    The What, How and Why
    Berlin PHP Usergroup, November 7 2017

    View full-size slide

  2. About Me

    Hi, I’m Marco Petersen!

    My home on the internet: ma.rcopetersen.com

    My nickname on the interwebs: ocrampete16

    Slides are published on Speaker Deck

    View full-size slide

  3. Is REST really dead?

    View full-size slide

  4. What is REST?

    REpresentational State Transfer

    2000, Roy Fielding’s PhD dissertation

    Architectural concept for network-based software

    View full-size slide

  5. What is REST?

    URIs serve as unique identifiers for resources

    HTTP verbs denote what is to be done with a resource

    Leverages HTTP features (headers, status codes etc.)

    HATEOAS (Hypertext As The Engine Of Application State)

    View full-size slide

  6. /users // all users
    /users/1 // user with the ID “1”
    /users/1/avatar // user 1’s avatar

    View full-size slide

  7. What is REST?

    URIs serve as unique identifiers for resources

    HTTP verbs denote what is to be done with a resource

    Leverages HTTP features (headers, status codes etc.)

    HATEOAS (Hypertext As The Engine Of Application State)

    View full-size slide

  8. // create a new user
    POST /users
    // replace a user’s avatar
    PUT /users/1/avatar
    // delete the user’s high score with the ID “42”
    DELETE /users/2/high-scores/42

    View full-size slide

  9. What is REST?

    URIs serve as unique identifiers for resources

    HTTP verbs denote what is to be done with a resource

    Leverages HTTP features (headers, status codes etc.)

    HATEOAS (Hypertext As The Engine Of Application State)

    View full-size slide

  10. What is REST?

    URIs serve as unique identifiers for resources

    HTTP verbs denote what is to be done with a resource

    Leverages HTTP features (headers, status codes etc.)

    HATEOAS (Hypertext As The Engine Of Application State)

    View full-size slide

  11. {
    "userId": 2,
    "name": "Leeroy Jenkins",
    "links": [
    {
    "href": "/users/2/high-scores",
    "rel": "high-scores",
    "type" : "GET"
    }
    ]
    }

    View full-size slide

  12. What is GraphQL?

    Developed in 2012 by Facebook, publicly released in 2015

    Query language

    Lots of tools and libraries to facilitate development of
    GraphQL-compatible APIs

    Reference implementation in (server-side) Javascript

    View full-size slide

  13. What is GraphQL?

    What You Want Is What You Get

    Single endpoint for all requests (typically
    /graphql
    )

    Relies on own conventions instead of using HTTP

    All client requests are POST

    All server responses are 200 OK

    Uses queries and mutations for fetching and modifying data

    And much more!

    View full-size slide

  14. Querying Data
    POST /graphql
    {
    user(id: "2") {
    name,
    birthdate,
    username
    }
    }
    200 OK
    {
    “data”: {
    “user”: {
    “name”: “Leeroy Jenkins”,
    “birthdate”: “1995-07-13”,
    “username”: “foobar”
    }
    }
    }

    View full-size slide

  15. Customizing Field Names
    POST /graphql
    {
    user(id: "2") {
    fullName: name,
    dateOfBirth: birthdate,
    username
    }
    }
    200 OK
    {
    “data”: {
    “user”: {
    “fullName”: “Leeroy Jenkins”,
    “dateOfBirth”: “1995-07-13”,
    “username”: “foobar”
    }
    }
    }

    View full-size slide

  16. Querying Subresources
    POST /graphql
    {
    me: viewer {
    fullname: name
    repositories(first: 2) {
    edges {
    node {
    name
    }
    }
    }
    }
    }
    200 OK
    {
    "data": {
    "me": {
    "fullname": "Foobar Spameggs",
    "repositories": {
    "edges": [
    {"node": {"name":"repo1"}},
    {"node": {"name": "repo2"}}
    ]
    }
    }
    }
    }

    View full-size slide

  17. What is GraphQL?

    What You Want Is What You Get

    Single endpoint for all requests (typically
    /graphql
    )

    Relies on own conventions instead of using HTTP

    All client requests are POST

    All server responses are 200 OK

    Uses queries and mutations for fetching and modifying data

    And much more!

    View full-size slide

  18. What is GraphQL?

    What You Want Is What You Get

    Single endpoint for all requests (typically
    /graphql
    )

    Relies on own conventions instead of using HTTP

    All client requests are POST

    All server responses are 200 OK

    Uses queries and mutations for fetching and modifying data

    And much more!

    View full-size slide

  19. What is GraphQL?

    What You Want Is What You Get

    Single endpoint for all requests (typically
    /graphql
    )

    Relies on own conventions instead of using HTTP

    All client requests are POST

    All server responses are 200 OK

    Uses queries and mutations for fetching and modifying data

    And much more!

    View full-size slide

  20. Mutations
    POST /graphql
    mutation CreateReviewForEpisode(
    1: Episode!,
    {“stars”: 5}: ReviewInput!
    ) {
    createReview(
    episode: 1, review: {“stars”: 5}
    ) {
    stars
    }
    }
    200 OK
    {
    "data": {
    "createReview": {
    "stars": 5
    }
    }
    }

    View full-size slide

  21. What is GraphQL?

    What You Want Is What You Get

    Single endpoint for all requests (typically
    /graphql
    )

    Relies on own conventions instead of using HTTP

    All client requests are POST

    All server responses are 200 OK

    Uses queries and mutations for fetching and modifying data

    And much more!

    View full-size slide

  22. Core Differences
    REST

    Architecture for APIs

    Utilizes HTTP to the
    fullest
    GraphQL

    Query language

    Uses HTTP as a “dumb”
    data transfer mechanism

    View full-size slide

  23. Core Differences
    REST

    Architecture for APIs

    Utilizes HTTP to the
    fullest
    GraphQL

    Query language

    Uses HTTP as a “dumb”
    data transfer mechanism

    View full-size slide

  24. Differences: Architecture vs Query Language
    REST

    Multiple endpoints

    Flexible in what requests it
    accepts

    No clear consensus on how
    to evolve APIs

    Returns entire resources (by
    default)
    GraphQL

    One endpoint for everything

    Limited to the query
    language

    API evolution is easy w/
    great tooling

    What You Want Is What
    You Get

    View full-size slide

  25. GET /users/1
    PUT /users/1/avatar
    POST /users/1/highscores

    // It’s inherently obvious what’s going on

    View full-size slide

  26. POST /graphql
    POST /graphql
    POST /graphql

    View full-size slide

  27. Differences: Architecture vs Query Language
    REST

    Multiple endpoints

    Flexible in what requests it
    accepts

    No clear consensus on how
    to evolve APIs

    Returns entire resources (by
    default)
    GraphQL

    One endpoint for everything

    Limited to the query
    language

    API evolution is easy w/
    great tooling

    What You Want Is What
    You Get

    View full-size slide

  28. Differences: Architecture vs Query Language
    REST

    Multiple endpoints

    Flexible in what requests it
    accepts

    No clear consensus on how
    to evolve APIs

    Returns entire resources (by
    default)
    GraphQL

    One endpoint for everything

    Limited to the query
    language

    API evolution is easy w/
    great tooling

    What You Want Is What
    You Get

    View full-size slide

  29. Differences: Architecture vs Query Language
    REST

    Multiple endpoints

    Flexible in what requests it
    accepts

    No clear consensus on how
    to evolve APIs

    Returns entire resources (by
    default)
    GraphQL

    One endpoint for everything

    Limited to the query
    language

    API evolution is easy w/
    great tooling

    What You Want Is What
    You Get

    View full-size slide

  30. Differences: Resources vs What You See Is What You Get
    REST

    Clients receive data in a
    predefined structure

    Easier to cache

    Multiple API calls may be
    necessary

    No information on which
    fields are actually used
    GraphQL

    Clients receive data
    structured the way they
    need it

    Less cache hits

    Can fetch all data with a
    single API call

    Granular information on
    which fields are used

    View full-size slide

  31. Differences: Resources vs What You See Is What You Get
    REST

    Clients receive data in a
    predefined structure

    Easier to cache

    Multiple API calls may be
    necessary

    No information on which
    fields are actually used
    GraphQL

    Clients receive data
    structured the way they
    need it

    Less cache hits

    Can fetch all data with a
    single API call

    Granular information on
    which fields are used

    View full-size slide

  32. Differences: Resources vs What You See Is What You Get
    REST

    Clients receive data in a
    predefined structure

    Easier to cache

    Multiple API calls may be
    necessary

    No information on which
    fields are actually used
    GraphQL

    Clients receive data
    structured the way they
    need it

    Less cache hits

    Can fetch all data with a
    single API call

    Granular information on
    which fields are used

    View full-size slide

  33. Differences: Resources vs What You See Is What You Get
    REST

    Clients receive data in a
    predefined structure

    Easier to cache

    Multiple API calls may be
    necessary

    No information on which
    fields are actually used
    GraphQL

    Clients receive data
    structured the way they
    need it

    Less cache hits

    Can fetch all data with a
    single API call

    Granular information on
    which fields are used

    View full-size slide

  34. Core Differences
    REST

    Architecture for APIs

    Utilizes HTTP to the
    fullest
    GraphQL

    Query language

    Uses HTTP as a “dumb”
    data transfer mechanism

    View full-size slide

  35. Differences: Utilizing HTTP vs merely transferring data
    REST

    Caching is easy

    HTTP verbs carry more
    semantic information

    Clearly defined protocol
    for marking errors
    GraphQL

    Cannot cache at the
    network level

    Queries/mutations not as
    precise

    Hard to infer errors
    programmatically

    View full-size slide

  36. Caching: REST vs GraphQL
    Caching Types REST GraphQL
    Client Caching (browser etc.) yes yes, but it’s harder and most
    won’t bother
    Network Caching (Varnish, Squid
    etc.)
    yes no
    Application Caching (Redis,
    Memcache etc.)
    yes yes

    View full-size slide

  37. Differences: Utilizing HTTP vs merely transferring data
    REST

    Caching is easy

    HTTP verbs carry more
    semantic information

    Clearly defined protocol
    for marking errors
    GraphQL

    Cannot cache at the
    network level

    Queries/mutations not as
    precise

    Hard to infer errors
    programmatically

    View full-size slide

  38. Differences: Utilizing HTTP vs merely transferring data
    REST

    Caching is easy

    HTTP verbs carry more
    semantic information

    Clearly defined protocol
    for marking errors
    GraphQL

    Cannot cache at the
    network level

    Queries/mutations not as
    precise

    Hard to infer errors
    programmatically

    View full-size slide

  39. If you can’t decide which to use… use both!

    Option 1: Add a
    /graphql
    endpoint and implement the API
    from scratch

    Option 2: Have a GraphQL server act as a data proxy to other
    REST APIs

    Easier, but slight performance penalty

    Cache as much as possible to mitigate performance hits

    View full-size slide

  40. To recap...

    REST is an API architecture style, GraphQL a query language

    GraphQL is a good alternative, not REST 2.0

    If you’re happy with REST, no reason to change.

    If you’re have vastly different clients that require data in
    different combinations, GraphQL might be right for you.

    Or use both, if you could benefit from both approaches a lot.

    View full-size slide

  41. Thanks for listening!
    Questions?

    View full-size slide