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. 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
  2. What is REST? • REpresentational State Transfer • 2000, Roy

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

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

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

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

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

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

    to the fullest GraphQL • Query language • Uses HTTP as a “dumb” data transfer mechanism
  22. 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
  23. 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
  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
  25. 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
  26. 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
  27. 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
  28. 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
  29. 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
  30. Core Differences REST • Architecture for APIs • Utilizes HTTP

    to the fullest GraphQL • Query language • Uses HTTP as a “dumb” data transfer mechanism
  31. 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
  32. 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
  33. 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
  34. 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
  35. 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
  36. 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.