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.

3dd28ad260d202a12c2e93fc28fad5d7?s=128

Marco Petersen

November 07, 2017
Tweet

Transcript

  1. REST vs GraphQL The What, How and Why Berlin PHP

    Usergroup, November 7 2017
  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
  3. None
  4. None
  5. None
  6. Is REST really dead?

  7. What is REST? • REpresentational State Transfer • 2000, Roy

    Fielding’s PhD dissertation • Architectural concept for network-based software
  8. 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)
  9. /users // all users /users/1 // user with the ID

    “1” /users/1/avatar // user 1’s avatar
  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)
  11. // 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
  12. 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)
  13. 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)
  14. { "userId": 2, "name": "Leeroy Jenkins", "links": [ { "href":

    "/users/2/high-scores", "rel": "high-scores", "type" : "GET" } ] }
  15. 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
  16. 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!
  17. Querying Data POST /graphql { user(id: "2") { name, birthdate,

    username } } 200 OK { “data”: { “user”: { “name”: “Leeroy Jenkins”, “birthdate”: “1995-07-13”, “username”: “foobar” } } }
  18. 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” } } }
  19. 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"}} ] } } } }
  20. 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!
  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!
  22. 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!
  23. Mutations POST /graphql mutation CreateReviewForEpisode( 1: Episode!, {“stars”: 5}: ReviewInput!

    ) { createReview( episode: 1, review: {“stars”: 5} ) { stars } } 200 OK { "data": { "createReview": { "stars": 5 } } }
  24. 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!
  25. Core Differences REST • Architecture for APIs • Utilizes HTTP

    to the fullest GraphQL • Query language • Uses HTTP as a “dumb” data transfer mechanism
  26. Core Differences REST • Architecture for APIs • Utilizes HTTP

    to the fullest GraphQL • Query language • Uses HTTP as a “dumb” data transfer mechanism
  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
  28. GET /users/1 PUT /users/1/avatar POST /users/1/highscores … // It’s inherently

    obvious what’s going on
  29. POST /graphql POST /graphql POST /graphql …

  30. 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
  31. 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
  32. 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
  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
  34. 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
  35. 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
  36. 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
  37. Core Differences REST • Architecture for APIs • Utilizes HTTP

    to the fullest GraphQL • Query language • Uses HTTP as a “dumb” data transfer mechanism
  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
  39. 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
  40. 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
  41. 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
  42. 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
  43. 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.
  44. Thanks for listening! Questions?